Développement et versions du Plugin SDK

Développement, vérification, outils de publication et workflows 1.2, cache incrémental, outils externes et passerelle LSP publique.

Guide de développement, de vérification et de publication pour DDS Plugin SDK 1.2.0. L’audit de sécurité et la validation des vulnérabilités sont en attente ; la stabilité des API et les contrôles fonctionnels ne constituent pas une acceptation de sécurité.

Guide d’installation du SDK et des API

Modèles de développement et génération

Choisissez command, language, theme, job, browser ou configuration. init --dry-run indique la destination, l’inventaire des fichiers, les empreintes et les conflits sans écrire ni installer quoi que ce soit. Une exécution normale de init exige un nouveau répertoire réel. Chaque modèle comprend le code source, un manifeste, une déclaration, une licence/notice, des tests, un consommateur typé et un exemple exécutable. Les modèles browser et configuration comprennent une démonstration sur l’interface de boucle locale. Les dépendances générées sont épinglées sur l’archive GitHub exacte.

npx --no-install dds-plugin init example-plugin --template configuration --dry-run
npx --no-install dds-plugin init example-plugin --template configuration
cd example-plugin
npm install --ignore-scripts
npm run doctor
npm test
npm run typecheck
npm run example
npm run browser

dds-dev.json contient des données JSON aux limites définies pour les schémas de commandes, les paramètres, les catalogues de langues et les thèmes. generate produit du JSON d’exécution, des exports ESM, des types TypeScript d’entrée bruts/validés, des types de sortie et de paramètres, un JSON Schema et du XML de thème. Les valeurs par défaut de JSON Schema sont des annotations ; seule la validation des entrées du SDK les applique. La génération n’importe pas votre plugin. doctor vérifie les divergences, les métadonnées, les modules manquants et la présence des fichiers d’exécution générés dans la liste des fichiers autorisés du paquet.

npx --no-install dds-plugin generate . --check
npx --no-install dds-plugin generate . --dry-run
# Review the new files, then use the previous digest from the report:
npx --no-install dds-plugin generate . --expected-digest <previous-digest>

Le remplacement exige l’empreinte précédente exacte et des octets générés inchangés. Les modifications manuelles, fichiers supplémentaires, liens et verrous périmés interrompent le remplacement. En cas d’échec, seuls les éléments inchangés créés par cette tentative sont supprimés ; les éléments modifiés ou incertains sont conservés pour inspection. Les limites sont de 256 fichiers, 1 MiB par fichier et 4 MiB au total. Le verrou coordonne les générateurs coopératifs ; il ne protège pas contre un processus hostile écrivant simultanément dans le système de fichiers et ne fournit pas de transaction atomique entre répertoires. Les modèles propriétaires exigent des conditions fournies par l’appelant et conservent les fichiers de licence/notice hérités du SDK.

Tests déterministes et rejeu

createScenarioHost de /testing monte explicitement les jeux de données de test en mémoire sélectionnés pour les fichiers, le backend, les paramètres, les secrets et les tâches. Il démarre sans autorisation ni capacité accordée. createTestClock fournit des identifiants, une heure et des temporisateurs issus d’une graine sans modifier les objets globaux ; les temporisateurs de même échéance conservent leur ordre d’insertion. Attendez l’avancement de l’horloge pour débloquer les attentes virtuelles. Les UUID générés sont des données de test et non une source d’entropie cryptographique. Les valeurs par défaut existantes de createTestHost restent compatibles.

import {createScenarioHost} from '@altifigence/dds-plugin-sdk/testing';
const scenario = createScenarioHost({seed: 7, start: 1000,
  files: {'example.txt': 'synthetic'}, grants: ['workspace.read'],
});
try {
  // Activate your explicitly imported test plugin on scenario.host.
  scenario.faults.enqueue({operation: 'file.read', kind: 'delay', delayMs: 25});
  // Start its command, then await scenario.clock.advance(25).
} finally {
  await scenario.dispose();
  scenario.assertClean();
}

Les interfaces de simulation des défaillances modélisent retards, refus, déconnexions, corruption, épuisement et appels perdus ; les événements de test peuvent être supprimés, dupliqués ou inversés sans répéter les effets externes. replaceGrants désactive les plugins qui perdent leurs droits. Les instantanés de tâches en mémoire valident l’identité, la révision et les empreintes et modélisent la récupération après interruption sans exécution automatique. Ces jeux de test n’émulent pas la durabilité du système de fichiers et ne découvrent pas les handles du système d’exploitation. Un registre de propriété distinct suit les ressources explicitement enregistrées. Le nettoyage conserve le compte des callbacks en attente qui ignorent l’annulation jusqu’à leur terminaison effective. L’inspection des paramètres est désormais possible après libération ; les lectures de données restent refusées.

L’enregistrement exige synthetic: true et un inventaire explicite de jeux de test soumis à des limites. Les traces exportées contiennent uniquement les types d’opération, les identifiants de jeux de test, les temps, la graine/version et des empreintes chaînées. Utilisez des identifiants non sensibles ; les empreintes n’anonymisent pas les données devinables et le SDK ne peut pas déterminer si une entrée arbitraire est synthétique. Le rejeu pur vérifie l’ordre, les empreintes et l’identité des jeux de test puis renvoie leurs sorties sélectionnées ; il n’accepte aucun callback produisant des effets. Les limites comprennent 64 jeux de test, 1 024 événements et une trace de 1 MiB. Exécutez l’exemple development-tools fourni dans le paquet pour vérifier les défaillances, la récupération, la confidentialité et le nettoyage.

Diagnostics locaux et débogage

import {createDiagnosticSession, profileHost}
  from '@altifigence/dds-plugin-sdk/diagnostics';
const session = createDiagnosticSession({enabled: true, sampleEvery: 10});
const measured = profileHost(host, session);
try {
  await measured.executeCommand('example', 'run', {});
} finally {
  measured.dispose();
  console.log(session.snapshot());
  session.dispose();
}

Les diagnostics sont désactivés par défaut et restent exclusivement locaux. Les rapports contiennent des codes fixes d’opération, d’état et d’erreur, des identifiants de corrélation, des durées et des décomptes de ressources ; aucune API ne permet d’y inclure le corps des documents, les chemins, les entrées, les corps de sortie ou du texte d’exception arbitraire. Les nombres d’octets, profondeurs de file et mesures de mémoire sont des estimations explicites du propriétaire. profileTransport mesure jusqu’à la résolution de l’appel encapsulé ; avec fetch, cela correspond aux en-têtes de réponse et non à la fin du corps. Les enregistrements terminés utilisent un tampon circulaire borné et une expiration passive ; aucun temporisateur de diagnostic en arrière-plan ni téléversement n’est créé. Les valeurs par défaut sont de 128 événements/60 secondes ; les maximums sont de 256 événements/5 minutes, 64 mesures en cours et 256 KiB par rapport.

npx --no-install dds-plugin dev . --trust-local-code --profile --command greet --input '{"name":"Ada"}'
npx --no-install dds-plugin dev . --trust-local-code --debug --debug-wait --timeout-ms 30000 --command greet --input '{"name":"Ada"}'

Le mode debug expose uniquement un inspecteur éphémère sur 127.0.0.1 dans le processus enfant détenu. --debug-wait suspend l’exécution avant l’import du plugin et exige --debug. Le budget total d’exécution inclut l’attente du débogueur et ne dépasse pas 30 secondes. La fin, l’annulation et le dépassement du délai terminent le processus enfant détenu et l’inspecteur. Profilage et débogage exigent tous deux une confiance explicite dans le code local ; aucun ne constitue un bac à sable. Un plantage ou un arrêt forcé peut empêcher la production du rapport de profilage, et les sorties brutes stdout/stderr du plugin restent un flux distinct soumis à des limites, sans masquage automatique.

Outils de développement · Tests · Diagnostics · Compatibilité

Conformité de l’hôte

Le module /conformance exécute des sondes synthétiques versionnées sur les adaptateurs d’hôte, de paramètres, d’espace de travail, de localisation, de test, de diagnostic et de développement que vous fournissez explicitement. Il distingue les profils pris en charge, non pris en charge et en échec et inclut l’hôte, la version, le runtime, la plateforme, l’identifiant du contrôle, la durée et le nettoyage. Une fonctionnalité déclarée dont l’adaptateur manque ou est défectueux échoue ; les fonctionnalités facultatives inconnues sont consignées sans sonde. Les commandes, permissions et l’annulation sont requises par défaut.

import {runConformance, formatConformanceReport}
  from '@altifigence/dds-plugin-sdk/conformance';
import {createPluginHost} from '@altifigence/dds-plugin-sdk';
const report = await runConformance({
  identity: {host: 'My host', version: '1.0.0', runtime: 'Node 24', platform: 'linux-x64'},
  features: ['commands', 'permissions', 'cancellation'],
  adapters: {host: options => createPluginHost(options)},
});
console.log(formatConformanceReport(report));

Remplacez la fabrique d’hôte par votre adaptateur et exécutez également les tests de votre plugin. L’utilitaire Node /conformance-node ne crée que de nouveaux jeux de test temporaires et des serveurs éphémères sur la boucle locale. L’exemple pour navigateur exécute les profils disponibles et indique les fonctionnalités Node absentes comme non prises en charge. Les sondes rapides échantillonnent les contrats ; les exemples liés et les tests de version couvrent des parcours plus larges de langage, de récupération et de stockage. Un rapport constitue une preuve de test, pas un certificat de confiance.

Le délai par défaut est de 10 secondes par cas, avec un maximum de 30 secondes. Un dépassement de délai ou une annulation interrompt les cas suivants ; un échec de nettoyage fait échouer le cas, et un nettoyage en attente reste non vérifié. Les adaptateurs de confiance exécutés dans le processus peuvent bloquer de manière synchrone et conserver les droits ambiants. Les rapports excluent les corps d’erreur des fournisseurs, les charges utiles, les jetons et les chemins ; choisissez des libellés d’identité non sensibles. Aucun rapport n’est téléversé automatiquement.

Prise en charge et migration du SDK

API_SUPPORT.json répertorie chaque module exporté, nom d’exécution, déclaration, empreinte de déclaration, environnement et niveau de stabilité. Les API stables 1.x suivent le versionnement sémantique : les ajouts compatibles donnent lieu à une version mineure, et les modifications incompatibles d’une API stable exigent une nouvelle version majeure. artifact-resume-browser reste expérimental et nécessite des versions exactes du SDK et du navigateur ainsi qu’une nouvelle validation dans le navigateur. La découverte des capacités facultatives et la vérification des permissions actuelles restent obligatoires.

La politique des versions stables s’applique à partir de 1.0.0. La dernière version mineure stable reçoit les correctifs ordinaires ; la version mineure précédente reste éligible aux correctifs de sécurité critiques pendant 90 jours dans un runtime pris en charge. Aucune API stable n’est dépréciée dans 1.0.0. Les dépréciations sont annoncées au moins deux versions mineures et six mois avant leur suppression dans une version majeure. Les RC et préversions sont remplacées. Cette politique open source ne garantit aucun délai de réponse commercial.

La validation serveur et CLI couvre Windows/Linux avec Node 22 ou 24 à jour et les déclarations avec TypeScript 5.9.3. La prise en charge de Node 22 prend fin le 2027-04-30 et celle de Node 24 le 2028-04-30. Les justificatifs de version identifient les versions de correctif exactes, les images du système et la version du navigateur. Les autres runtimes et combinaisons navigateur/stockage nécessitent leur propre validation. Le SDK reste sans dépendance npm d’exécution.

Les plugins stables 1.0 utilisent >=1.0.0 <2.0.0 ; augmentez la version minimale lorsque vous adoptez une API ultérieure. Les paquets RC1 conservent leur dépendance pair exacte 1.0.0-rc.1. Pour la modifier, revalidez et publiez une nouvelle version du plugin ; gardez les archives précédentes immuables. Les archives anciennes sont des entrées d’interopérabilité et non des branches maintenues. Après un redémarrage, établissez une nouvelle connexion avec les autorisations actuelles ; la récupération lit l’état validé sans relancer les travaux.

Validation de la version

L’audit de sécurité et la validation des vulnérabilités sont en attente conformément au report décidé par le propriétaire le 2026-10-05. Les résultats fonctionnels, de compatibilité et de performance ne constituent pas une acceptation de sécurité. La revue conservée reprendra séparément ; cette version ne doit pas être présentée comme ayant réussi cet audit.

Le jeu de test combiné sollicite simultanément le langage et les paramètres, les modifications revues, les tâches de commandes, la surveillance de projet, le téléversement/téléchargement et le stockage conservé. Il vérifie les interruptions, réponses malformées, révocations, changements de génération, récupération et nettoyage des ressources. Des tests distincts du système de fichiers et des processus couvrent les processus enfants tués, la corruption, les écritures échouées, l’expiration et l’annulation ignorée. Le rapport de validation RC relie les commandes reproductibles aux limites de chaque résultat.

Les mesures de performance consignent cinq échantillons dans de nouveaux processus pour chaque profil Windows/Linux et Node 22/24, avec médiane et dispersion, temps CPU, mémoire échantillonnée, durées d’import/démarrage/surveillance et volumes logiques des charges disque/HTTP. Les seuils de référence proviennent de ces échantillons mesurés et constituent des garde-fous grossiers contre les régressions, pas un SLA de latence. Ils ne mesurent pas le trafic physique du disque et ne garantissent pas la découverte de tous les handles du système d’exploitation.

npm ci --ignore-scripts
npm run check
npm run example:conformance -- --json
npm run example:combined -- --faults
npm run benchmark:combined
npm run example:conformance-browser

Conformité · Inventaire des API · Politique de prise en charge · Validation RC

Contenu de la version stable 1.0

Le paquet 1.0 d’origine comprend 38 exports et 86 schémas avec déclarations, exemples, LICENSE et NOTICE. La version 1.1 ajoute les outils de publication ci-dessous ; la version 1.2 ajoute les sections workflow/cache/outils/LSP ci-dessous. Les justificatifs de version distinguent les sources, CI et empreintes exactes, les nouveaux consommateurs et les preuves de navigateur réutilisées.

Pour revenir à une version antérieure, arrêtez les travaux détenus et sélectionnez explicitement des archives compatibles conservées du SDK et des plugins ainsi qu’un export de configuration. Vérifiez les autorisations actuelles et créez une nouvelle connexion. La récupération des résultats se limite à la lecture ; les effets externes et les paramètres incompatibles ne sont pas annulés automatiquement. Testez les formats et les fonctionnalités facultatives réellement utilisés.

Contenu, migration et prise en charge des versions

Bundles hors ligne et SBOM

Le SDK 1.1 ajoute cinq points d’entrée facultatifs réservés à Node : /bundles, /provenance, /updates, /updates-node et /upstream. Le paquet contient 43 exports, 96 schémas, des déclarations et des exemples exécutables, sans dépendance npm d’exécution. Les API 1.0 existantes et les archives DDS .tgz non signées restent compatibles.

lockBundleDependency verrouille une arborescence ESM/CommonJS revue sur une version exacte, une source HTTPS, une empreinte canonique des fichiers, une carte des dépendances, LICENSE/NOTICE et une décision explicite de redistribution. L’empreinte décrit l’arborescence revue ; ce n’est pas l’empreinte d’une archive amont. createPluginBundle intègre l’archive d’origine du plugin DDS et les métadonnées de version, un graphe acyclique de dépendances à version unique et un SBOM CycloneDX 1.6 déterministe.

verifyPluginBundle vérifie l’instantané exact d’octets soumis à des limites. installPluginBundle exige son expectedSha256, approved: true et un nouveau répertoire sous un parent détenu par l’opérateur. Il n’exécute ni npm, ni scripts de cycle de vie, ni téléchargements, ni code de plugin. Les dépendances n’héritent d’aucune nouvelle autorisation. Le SDK de l’hôte est une dépendance distincte. Les extensions natives, cartes d’exports et la résolution arbitraire de dépendances npm sortent du cadre de ce format.

Limites : 32 paquets de dépendances, 1 024 fichiers développés, 4 MiB par fichier de dépendance, 32 MiB de contenu développé et 48 MiB de bundle encodé. L’archive racine d’origine possède ses propres limites plus strictes. Les versions manquantes ou contradictoires, cycles, dépendances orphelines, empreintes modifiées, licences/NOTICE manquantes, chemins/liens et collisions entre fichiers et répertoires sont rejetés. Les installations échouées conservent la nouvelle destination pour inspection. Excluez les écrivains concurrents ; cet outil n’est pas un bac à sable du système d’exploitation.

Signatures détachées et confiance de l’opérateur

createProvenanceStatement lie le nom, la version et le SHA-256 exacts du bundle, l’éditeur, la révision source et les dates d’émission/expiration. signPluginProvenance utilise un KeyObject Ed25519 détenu par l’appelant. canonicalProvenancePayload expose DDS-PROVENANCE-V1 suivi du JSON canonique pour qu’un autre signataire puisse reproduire la même charge utile. Le SDK ne fournit aucune clé privée de signature ni autorité de signature du produit DDS.

verifyPluginProvenance prend les racines de confiance choisies par l’opérateur, les liens éditeur/sujet, l’heure actuelle, la validité/révocation des clés et des preuves de révocation horodatées. La vérification hors ligne utilise les preuves fournies et applique le même budget de fraîcheur ; elle ne récupère jamais elle-même de nouvelles informations de révocation. Une nouvelle clé de paquet n’est pas fiable tant que l’opérateur ne l’a pas ajoutée. Des racines explicitement chevauchantes permettent la rotation. La dérive d’horloge maximale est de cinq minutes et l’âge maximal des preuves de 30 jours ; choisissez des limites plus strictes au besoin.

Les justificatifs distinguent somme de contrôle, signature, éditeur et politique et renvoient toujours executionAuthorized: false. Une signature ne prouve pas la sûreté du code et n’accorde aucune autorisation d’exécution, d’accès aux données ou de bac à sable. Les anciens paquets non signés exigent envelope: null et allowUnsigned: true, tout en signalant l’absence de signature et un éditeur non vérifié. L’audit de sécurité et la validation des vulnérabilités restent indépendamment en attente.

Revoir, activer et revenir en arrière

createPluginUpdatePlan compare les anciennes et nouvelles versions, API, autorisations, sources et empreintes de dépendances, outils déclarés, licences, empreintes de paramètres, identité de migration, signature et clé, puis fixe l’empreinte de revue. createPluginUpdateController détient l’hôte autorisé actuel et les paramètres ainsi que les interfaces getPolicy/prepare de l’opérateur. Stage vérifie le candidat et en prend un instantané ; approve doit correspondre exactement à l’empreinte du plan, aux autorisations et à l’identifiant de clé. Activate vérifie les paramètres actuels et réévalue la confiance avant et après la préparation d’un hôte candidat distinct.

wait reporte l’activation tant que des tâches sont en cours. retain-old laisse les anciennes tâches sur leurs hôtes, paramètres et empreintes d’origine et dirige les nouvelles exécutions vers le nouvel hôte après la bascule. execute renvoie l’empreinte du plugin avec chaque résultat. Les tâches ne sont pas annulées implicitement. Le remplacement des paramètres invalide une approbation en attente ; les modifications simultanées et préparations échouées conservent l’état précédent ou le signalent explicitement. Le retour arrière prépare l’ancien paquet et les anciens paramètres comme une nouvelle mise à jour revue et exige une confiance actuelle et une nouvelle approbation.

La préparation et les migrations passent par des interfaces de confiance détenues par l’opérateur. Ni le retour arrière ni un échec n’annulent les fichiers externes, requêtes réseau ou autres effets. reversible est une métadonnée de revue, pas une promesse d’annulation automatique. Un journal Node est en ajout seulement, à écrivain unique et situé hors de l’espace de travail, avec CAS sur la révision exacte et des limites de 256 enregistrements / 128 KiB par enveloppe / 8 MiB au total. Archivez-le sous le contrôle de l’opérateur avant d’ouvrir un nouveau journal lorsque la limite est atteinte.

inspectNodeUpdateJournal lit l’état persistant sans rejeu. Un plantage pendant preparing ou un accusé de réception ambigu exige une lecture explicite de l’hôte et des paramètres ; reconcilePluginUpdateJournal consigne une empreinte ancienne/nouvelle connue et approuvée et une empreinte de paramètres. Les fins de journal corrompues exigent une inspection/réparation par l’opérateur. recoverStaleLock ne récupère que le verrou d’un écrivain de la même machine dont la mort est prouvée. Cela ne garantit ni une transaction hôte/paramètres entre processus, ni une atomicité universelle en cas de coupure de courant.

Contrôles amont explicites et candidats

fetchUpstreamArtifact exige un appel explicite, enabled: true, une URL source, une version et une empreinte exactes, une liste d’URL autorisées exacte, une politique hors ligne, un budget d’octets et une échéance. Les cibles de redirection doivent aussi être autorisées. Il n’envoie ni cookies ni en-têtes d’authentification, ne réessaie rien automatiquement et signale verified / digest-mismatch / unavailable / offline / unverified avec l’heure d’observation. Tout tag ou empreinte modifié exige une nouvelle revue. HTTP sur la boucle locale est disponible uniquement via une option de test explicite.

Les adaptateurs peuvent publier un upstream-manifest revu contenant l’inventaire des API, la révision source exacte, l’intégralité de la licence/NOTICE et les empreintes des fichiers. inspectUpstreamManifest relie ces métadonnées aux octets téléchargés ; il n’analyse pas du code source arbitraire et ne déduit pas l’autorisation de redistribution. createUpstreamCandidate renvoie les différences d’API, de fichiers et de licences ainsi qu’un patch contenant l’empreinte précédente et la source de remplacement. La correspondance avec une matrice exacte de versions reste non vérifiée sans contrôle fonctionnel du développeur ; une API requise manquante est non prise en charge.

Un candidat pris en charge exige toujours une revue humaine. Son tableau automaticActions est vide ; ces API ne créent pas de branche, ne fusionnent pas, ne publient pas, n’approuvent pas de nouvelles autorisations et n’installent pas de surveillance. L’hôte est responsable de l’exécution et de l’annulation des tests d’adaptateur. L’exemple public complet ci-dessous utilise uniquement des jeux de test locaux. Les API workflow/cache/outils/LSP sont disponibles dans les sections 1.2 ci-dessous.

node node_modules/@altifigence/dds-plugin-sdk/examples/release-tools/run.mjs

Types, API, limites et code source exécutable complet

Workflows de commandes et récupération explicite

Le SDK 1.2 ajoute sept exports facultatifs : /workflows, /workflows-node, /workflow-cache, /workflow-cache-node, /tool-streams, /tool-streams-node et /lsp-node. Le paquet actuel comporte 50 exports, 107 schémas, des déclarations TypeScript et des exemples installés indépendants, sans dépendance npm d’exécution. Seul /tool-streams est portable vers le navigateur ; les autres nouveaux exports exigent Node. Le protocole d’espace de travail et les API 1.x existants restent compatibles. Un plugin qui importe une nouvelle API 1.2 doit déclarer 1.2.0 comme version minimale du SDK.

prepareWorkflowPlan valide les identifiants de commandes enregistrées, l’unicité des étapes, l’absence de cycles dans les dépendances, les schémas fermés de données d’entrée/sortie et les liaisons de sortie requises avant l’exécution. Chaque entrée est une valeur littérale {value} ou une liaison {step, path} vers une dépendance explicite. Les contraintes de schéma doivent correspondre exactement. Le plan immuable lie ses commandes, autorisations, portée et entrées à un SHA-256. run exige approved: true et cette empreinte revue exacte. Les interfaces authorize et execute de l’hôte restent détenues par l’opérateur.

createCommandJobExecutor connecte un PluginHost isolé existant, choisi par resolveHost, qui renvoie la portée exacte de l’hôte, les autorisations de l’étape et l’empreinte du plugin. Les autorisations ne sont jamais combinées entre étapes. Les droits actuels sont vérifiés avant l’exécution, après les résultats et avant toute réutilisation. continue termine les branches indépendantes et bloque les descendants en échec ; fail-fast annule les étapes restantes. Les enregistrements conservent les identifiants de tâche parente et de tentative, les tâches individuelles, les empreintes d’entrée/sortie, les artefacts, les motifs et les horodatages. Un résultat issu du cache n’a pas de nouvel identifiant de tâche et ne peut pas revendiquer des artefacts de tâche modifiables.

recover lit un point de contrôle stocké et signale les travaux en attente/en cours comme interrompus sans les exécuter. Une reprise manuelle fournit l’enregistrement précédent exact et previousAttemptId dans une nouvelle approbation, crée une nouvelle tentative et ne conserve que les résultats réussis correspondants et non expirés. retrySteps réexécute les étapes sélectionnées et leurs descendants, même dans un DAG non ordonné. Une sortie expirée exige une sélection explicite de nouvelle tentative ; une modification du schéma, de l’entrée, des autorisations ou de l’empreinte du plugin exige un nouveau plan. Un exécuteur qui ignore l’annulation reste compté comme non terminé et empêche les nouvelles tentatives de se chevaucher.

createNodeWorkflowStore utilise des répertoires réels et disjoints de stockage/espace de travail, des marqueurs de portée et d’identité du système de fichiers, un seul écrivain, des enveloppes avec somme de contrôle et des points de contrôle CAS. Après un plantage connu, recoverStaleLock explicite n’accepte qu’un propriétaire de la même machine dont la mort est prouvée. Le nettoyage par défaut traite les enregistrements corrompus reconnus et les écritures inachevées en préservant les fichiers/liens inconnus. cleanup({expiredBefore}) peut aussi supprimer les enregistrements terminaux expirés ; les enregistrements actifs restent disponibles pour récupération. Windows ne revendique ni fsync de répertoire ni durabilité face aux coupures de courant. Limites : 64 étapes, 8 étapes simultanées, délai de workflow de 10 minutes, 64 KiB par résultat, 1 MiB de sorties combinées, enregistrements de 2 MiB, 64 enregistrements conservés et conservation des résultats partiels pendant 24 heures au maximum.

Types, API, limites et exemples exécutables complets

Cache déterministe et exécution incrémentale

fingerprintWorkflowInputs calcule une empreinte des octets réels des fichiers ainsi que de la version du SDK, de la portée de l’espace de travail et de sécurité, du schéma et des entrées de commande, des empreintes de plugin et d’outil, des paramètres, de l’environnement déclaré et des autorisations. mtime et le chemin seuls ne constituent jamais une identité de contenu. L’opérateur déclare explicitement optIn, deterministic, declaredInputsComplete et secretDependent. Les entrées inconnues ou incomplètes, le non-déterminisme, la dépendance à un secret, un environnement manquant/non déclaré et les entrées faisant référence à un secret contournent le cache avec un motif. L’hôte doit également exclure les secrets bruts et les effets de bord ; le SDK ne peut pas déduire les entrées cachées.

createWorkflowCache vérifie de nouveau les droits actuels lors de lookup/fill/after-fill/hit/return et contrôle les empreintes des valeurs, la portée, les autorisations et l’expiration. Les échecs de cache simultanés admissibles partagent un seul calcul ; l’annulation d’un appelant en attente n’annule pas les autres. Les valeurs expirées ou endommagées sont des absences de cache. TTL/LRU, les budgets d’entrées/valeurs et le nettoyage du stockage détenu contrôlent le stockage ; les échecs d’écriture conservent les résultats calculés avec un motif explicite. Les résultats faisant référence à des secrets ne sont jamais conservés. Les limites d’empreinte sont de 64 fichiers, 4 MiB chacun et 16 MiB au total ; celles du cache sont de 512 entrées, 16 MiB de valeurs conservées, huit calculs et 60 secondes par calcul.

L’exemple de workflow ne consulte le cache qu’après la réussite des dépendances actuelles. Un fichier modifié invalide son étape ; des sorties modifiées invalident les empreintes d’entrée des dépendants. Une dépendance en échec bloque le parent avant la recherche d’un résultat parent en cache. Les justificatifs distinguent hit, miss, shared et bypass, l’exécution réelle de la réutilisation, les compteurs de cache, les octets stockés et les temps locaux. L’état durable du cache utilise des répertoires propriétaires disjoints et un remplacement atomique, avec récupération des écritures orphelines et de la corruption ; il ne supprime pas les fichiers source.

Types, API, limites et exemples exécutables complets

Flux de sortie des outils enregistrés

createToolStreamParser est un décodeur portable UTF-8 JSONL/texte soumis à des limites. Attendez write(bytes, stdout/stderr) pour respecter la contre-pression et n’appelez finish qu’après la fin des deux flux. Il préserve les caractères multioctets fragmentés et les dernières lignes partielles, en émettant des événements corrélés de journal, progression, diagnostic et type inconnu. Un UTF-8 malformé ou une limite stricte interrompt l’analyse. Les chemins relatifs de diagnostic, les positions ordonnées et les niveaux de gravité sont validés ; l’éditeur consommateur doit aussi valider les positions par rapport au texte actuel du document. createJobToolEventSink relie progression et journaux à un JobReporter existant et confie les diagnostics à un récepteur détenu par l’appelant.

L’exécuteur Node facultatif accepte des enregistrements fixes de l’opérateur : backend/outil/version, exécutable absolu et implémentations sélectionnées épinglées, sonde de version exacte, environnement explicite, schéma d’entrée fermé et emplacements d’arguments scalaires requis. Les emplacements de fichiers doivent désigner des fichiers relatifs existants dans l’espace de travail. Un appel de plugin ne choisit qu’un outil/version déjà enregistré et une entrée validée ; il ne peut pas choisir de shell ou d’exécutable. Les droits actuels sont vérifiés avant la préparation et le démarrage, à chaque événement et après la fin. Les justificatifs conservent le code de sortie, le motif d’annulation/échec et les statistiques de sortie.

Les valeurs littérales de secret/chemin connues sur une seule ligne sont masquées après assemblage de la ligne, y compris lorsque les fragments sont séparés ; les secrets encodés ou inconnus ne sont pas détectés automatiquement. L’exécuteur ne détient que son enfant direct et ses tubes et les ferme lors d’une annulation ou d’une fermeture. Il ne parcourt ni ne tue les arbres de processus non liés ou descendants et ne constitue pas un bac à sable du système d’exploitation. Limites : fragments de 64 KiB, lignes de 16 KiB, 2 MiB de sortie totale, 4 096 événements, huit écritures en file, récepteurs de cinq secondes, 32 outils et quatre exécutions simultanées. Une sonde distincte de cinq secondes/16 KiB vérifie la version configurée.

L’outil de test redistribuable écrit pour le SDK vérifie l’UTF-8/JSONL fragmenté, les dernières sorties, les codes de sortie non nuls, l’annulation et les limites. L’adaptateur réel est TypeScript 5.9.3 avec --noEmit --noLib --pretty false et un jeu de types intrinsèques jetable produisant TS2322. Fournissez explicitement une racine TypeScript existante et approuvée pour l’exécuter. Le SDK n’installe ni ne télécharge jamais automatiquement un outil externe ; les empreintes fournies n’authentifient pas indépendamment son éditeur.

Types, API, limites et exemples exécutables complets

Passerelle LSP publique sur stdio

createLspBridge connecte un processus stdio épinglé et explicitement approuvé aux requêtes et fournisseurs de langage existants du SDK. Il négocie le sous-ensemble LSP 3.17 pris en charge, les positions UTF-16 et les instantanés complets. capabilities distingue la prise en charge annoncée des exécutions réussies. Les correspondances prises en charge couvrent la complétion, le survol, la définition, les références, les symboles plats/hiérarchiques, l’aide de signature, prepare-rename/rename, le formatage de document/plage, les actions de code, les jetons sémantiques complets, le repliage et les indications intégrées : 15 fonctionnalités du SDK.

syncDocument et closeDocument gèrent didOpen/didChange/didClose. Les changements de version ou de génération actuelles annulent les travaux périmés, les identifiants de requêtes actives dupliqués sont rejetés et les réponses tardives ignorées. Les URI locales doivent se résoudre dans l’espace de travail sans liens ; les sources et cibles de modification exigent les droits actuels et un instantané exact ouvert ou fourni par l’hôte. Les résultats de renommage, formatage et action sont des propositions conditionnelles de modification de l’espace de travail avec empreintes de base, jamais des modifications automatiquement appliquées ni des commandes exécutables.

Les diagnostics ne sont acceptés qu’avec la version actuelle du document. Les notifications sans version ou périmées sont rejetées et comptées. Les fonctionnalités explicitement non prises en charge sont completion resolve/snippets, code-action resolve, les deltas sémantiques, les commandes serveur, les capacités dynamiques, les opérations sur les ressources, les transports socket et les diagnostics sans version. workspace/applyEdit renvoie applied:false. Limites : messages de 1 MiB, en-têtes de 8 KiB, sessions de 64 MiB/20 000 messages, 16 requêtes en attente et écritures en file, 32 documents/4 MiB de texte cumulé, délais de requête jusqu’à 30 secondes et 64 KiB de stderr écarté.

close envoie shutdown/exit et effectue un nettoyage borné du processus direct et des tubes, en distinguant l’accusé de réception gracieux, les serveurs ayant refusé ou planté et la fermeture effective du processus. Un serveur peut accuser réception de shutdown et nécessiter encore l’arrêt du processus détenu. Aucun redémarrage ni rejeu automatique n’a lieu : l’opérateur crée une nouvelle passerelle et renvoie explicitement les instantanés actuels sélectionnés. Les tests synthétiques couvrent le cadrage malformé, le plantage et les délais, l’annulation et les réponses tardives, les courses entre documents, le refus d’arrêt, les requêtes non prises en charge et chaque fonctionnalité mise en correspondance.

Le contrôle réel sur serveur indépendant utilise le projet communautaire typescript-language-server 5.3.0 avec TypeScript 5.9.3 : complétion, survol, définition, références, symboles, aide de signature, formatage et jetons sémantiques ont réussi. Les fichiers d’implémentation sélectionnés et Node sont épinglés, le chemin de tsserver est fixe et l’acquisition automatique de types est désactivée. Cette version du serveur omet initialize.serverInfo facultatif et envoie des diagnostics sans version ; ses diagnostics ne sont donc explicitement pas pris en charge par cette passerelle ; les diagnostics versionnés sont vérifiés avec le serveur synthétique indépendant. L’opérateur doit faire confiance à l’ensemble de l’outil installé et à ses accès au système d’exploitation.

La validation 1.2 inclut des consommateurs empaquetés indépendants, les déclarations, 107 schémas, les adaptateurs réels de compilateur/serveur et l’interopérabilité avec les archives publiques historiques. L’exemple de workflow distingue la récupération durable et la nouvelle tentative explicite du rejeu automatique. L’audit de sécurité et la validation des vulnérabilités restent en attente selon le report du propriétaire. Cette version ne constitue pas une validation de l’interface DDS, d’Engine, du planificateur Cloud, de Marketplace, de l’installateur ou d’un bac à sable de sécurité.

Types, API, limites et exemples exécutables complets

node node_modules/@altifigence/dds-plugin-sdk/examples/workflows/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs
node node_modules/@altifigence/dds-plugin-sdk/examples/tool-streams-browser/serve.mjs

Pour les adaptateurs réels, ajoutez les chemins absolus des installations existantes approuvées par l’opérateur. Les exemples par défaut n’utilisent que des jeux de test écrits pour le SDK et ne téléchargent jamais d’outil.

node node_modules/@altifigence/dds-plugin-sdk/examples/workflow-tools/run.mjs --typescript-root /absolute/path/to/typescript
node node_modules/@altifigence/dds-plugin-sdk/examples/lsp/run.mjs --typescript-root /absolute/path/to/typescript --language-server-root /absolute/path/to/typescript-language-server