Sviluppo e rilasci del Plugin SDK

Sviluppo, verifica, strumenti di rilascio e flussi di lavoro 1.2, cache incrementale, strumenti esterni e bridge LSP pubblico.

Indicazioni per lo sviluppo, la verifica e il rilascio di DDS Plugin SDK 1.2.0. L'audit di sicurezza e la validazione delle vulnerabilità sono in sospeso; lo stato stabile delle API e le verifiche funzionali non costituiscono un'accettazione di sicurezza.

Guida all'installazione dell'SDK e alle API

Modelli di sviluppo e generazione

Scegli command, language, theme, job, browser o configuration. init --dry-run indica la destinazione, l'inventario dei file, gli hash e i conflitti senza scrivere né installare. L'esecuzione normale di init richiede una nuova directory reale. Ogni modello comprende sorgenti, manifest, dichiarazione informativa, licenza/avvisi, test, un consumer tipizzato e un esempio eseguibile. I modelli browser e configuration includono una demo su loopback. Le dipendenze generate vincolano l'archivio GitHub esatto.

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 contiene dati JSON con limiti definiti per schemi dei comandi, impostazioni, cataloghi delle lingue e dati dei temi. generate produce JSON di runtime, esportazioni ESM, tipi TypeScript di input grezzi/validati, tipi di output/impostazioni, JSON Schema e XML dei temi. I valori predefiniti di JSON Schema sono annotazioni; solo la validazione degli input dell'SDK li applica. La generazione non importa il plugin. doctor verifica scostamenti, metadati, moduli mancanti e inclusione dei file di runtime generati nell'elenco dei file consentiti del pacchetto.

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>

La sostituzione richiede il digest precedente esatto e byte generati invariati. Modifiche manuali, file aggiuntivi, collegamenti e lock obsoleti bloccano la sostituzione. In caso di errore vengono rimosse solo le voci invariate appartenenti a quel tentativo; le voci modificate o incerte sono conservate per l'ispezione. I limiti sono 256 file, 1 MiB ciascuno e 4 MiB totali. Il lock coordina generatori cooperativi; non protegge da un processo ostile che scrive contemporaneamente nel filesystem e non costituisce una transazione atomica tra directory. I modelli proprietari richiedono condizioni fornite dal chiamante e conservano i file di licenza/avvisi ereditati dall'SDK.

Test deterministici e riproduzione

createScenarioHost di /testing monta esplicitamente le fixture in memoria selezionate per file, backend, impostazioni, segreti e job. Parte senza autorizzazioni né capacità. createTestClock fornisce ID basati su seed, ora e timer senza modificare gli oggetti globali; i timer con lo stesso istante mantengono l'ordine di inserimento. Attendi l'avanzamento dell'orologio per sbloccare le attese virtuali. Gli UUID generati sono dati di test, non entropia crittografica. I valori predefiniti esistenti di createTestHost restano compatibili.

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();
}

Le porte di fault modellano ritardi, rifiuti, disconnessioni, corruzione, esaurimento di risorse e chiamate perse; le fixture degli eventi possono essere eliminate, duplicate o invertite senza ripetere effetti esterni. replaceGrants disattiva i plugin che perdono l'autorità. Gli snapshot dei job in memoria validano identità, revisione e hash e modellano il recupero interrotto senza esecuzione automatica. Queste fixture non emulano la persistenza del filesystem né individuano handle del sistema operativo. Un registro separato del proprietario traccia le risorse registrate esplicitamente. Il teardown mantiene il conteggio delle callback in sospeso che ignorano l'annullamento finché non terminano effettivamente. L'ispezione delle impostazioni è ora leggibile dopo il rilascio delle risorse; le letture dei dati continuano a essere rifiutate.

La registrazione richiede synthetic: true e un inventario esplicito di fixture con limiti definiti. Le tracce esportate contengono solo tipi di operazione, ID delle fixture, tempi, seed/versione e hash concatenati. Usa ID non sensibili; gli hash non anonimizzano dati indovinabili e l'SDK non può classificare input arbitrari come sintetici. La riproduzione pura verifica ordine, hash e identità delle fixture e restituisce gli output delle fixture selezionate; non accetta callback con effetti. I limiti comprendono 64 fixture, 1.024 eventi e una traccia di 1 MiB. Esegui l'esempio development-tools incluso nel pacchetto per verificare fault, recupero, privacy e pulizia.

Diagnostica locale e debug

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();
}

La diagnostica è disattivata per impostazione predefinita ed è solo locale. I report contengono codici fissi di operazione/stato/errore, ID di correlazione, durate e conteggi delle risorse; non esiste un'API per corpi di documenti, percorsi, input, corpi di output o testo arbitrario delle eccezioni. Conteggi dei byte, profondità delle code e valori di memoria sono stime esplicite del proprietario. profileTransport misura fino alla risoluzione della chiamata avvolta, che per fetch coincide con gli header della risposta, non con il completamento del corpo. I record completati usano un buffer circolare con limiti e scadenza passiva; non ci sono timer diagnostici in background né caricamenti. I valori predefiniti sono 128 eventi/60 secondi; i massimi sono 256 eventi/5 minuti, 64 span in corso e 256 KiB per report.

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"}'

La modalità debug espone solo un inspector temporaneo su 127.0.0.1 nel processo figlio di proprietà. --debug-wait sospende l'esecuzione prima di importare il plugin e richiede --debug. Il tempo totale consentito include l'attesa del debugger ed è al massimo di 30 secondi. Completamento, annullamento e timeout terminano il processo figlio e l'inspector di proprietà. Profilazione e debug richiedono entrambi una fiducia esplicita nel codice locale; nessuno dei due è una sandbox. Crash o terminazione forzata possono impedire la produzione del report di profilazione, e stdout/stderr grezzi del plugin restano un flusso separato con limiti definiti, non oscurato automaticamente.

Strumenti di sviluppo · Test · Diagnostica · Compatibilità

Conformità dell'host

Il modulo /conformance esegue probe sintetici versionati sugli adattatori di host, impostazioni, workspace, localizzazione, test, diagnostica e sviluppo forniti esplicitamente. Distingue profili supportati, non supportati e falliti e include host/versione/runtime/piattaforma, ID della verifica, tempi e pulizia. Una funzionalità dichiarata con adattatore assente o guasto fallisce; le funzionalità opzionali sconosciute vengono registrate senza essere sondate. Comandi, permessi e annullamento sono richiesti per impostazione predefinita.

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));

Sostituisci la factory dell'host con il tuo adattatore ed esegui anche i test del plugin. L'helper Node /conformance-node crea solo nuove fixture temporanee e server loopback effimeri. L'esempio browser esegue i profili browser disponibili e segnala le funzionalità Node assenti come non supportate. I probe rapidi campionano i contratti; gli esempi collegati e i test di rilascio coprono percorsi più ampi di linguaggio, recupero e archiviazione. Un report è una prova di test, non un certificato di fiducia.

Le scadenze predefinite sono di 10 secondi per caso, con un massimo di 30 secondi. Timeout o annullamento interrompono i casi successivi; un errore di pulizia fa fallire il caso e la pulizia in sospeso resta non verificata. Gli adattatori fidati nello stesso processo possono bloccarsi sincronicamente e mantenere l'autorità dell'ambiente. I report escludono corpi degli errori del provider, payload, token e percorsi; scegli etichette identificative non sensibili. Nessun report viene caricato automaticamente.

Supporto e migrazione dell'SDK

API_SUPPORT.json elenca ogni modulo esportato, nome di runtime, dichiarazione, digest della dichiarazione, ambiente e stabilità. Le API stabili 1.x seguono il versionamento semantico: le aggiunte compatibili usano un rilascio minor, mentre le modifiche incompatibili a API stabili richiedono una nuova major. artifact-resume-browser resta sperimentale e necessita di una versione esatta di SDK/browser con una nuova accettazione sul browser. Restano necessari il rilevamento delle capacità opzionali e i permessi correnti.

La politica della linea stabile si applica dalla 1.0.0. L'ultima minor stabile riceve correzioni ordinarie; la minor precedente resta idonea a correzioni critiche di sicurezza per 90 giorni su un runtime supportato. Nessuna API stabile è deprecata nella 1.0.0. Le deprecazioni sono annunciate per almeno due rilasci minor e sei mesi prima della rimozione in una versione major. RC e anteprime vengono sostituite. Questa politica open source non promette tempi di risposta commerciali.

L'accettazione di server e CLI copre Windows/Linux con Node 22 o 24 aggiornato alle patch e le dichiarazioni con TypeScript 5.9.3. Il supporto di Node 22 termina il 2027-04-30 e quello di Node 24 il 2028-04-30. Le ricevute di rilascio identificano le versioni patch esatte, le immagini del sistema operativo e la build del browser. Altri runtime e combinazioni di browser/archiviazione richiedono un'accettazione propria. L'SDK continua a non avere dipendenze npm di runtime.

I plugin stabili 1.0 usano >=1.0.0 <2.0.0; aumenta il minimo quando adotti un'API successiva. I pacchetti RC1 mantengono il peer esatto 1.0.0-rc.1. Per cambiarlo, rivalida e pubblica una nuova versione del plugin; mantieni immutabili gli archivi precedenti. Gli archivi legacy sono input di interoperabilità, non linee mantenute. Dopo un riavvio stabilisci una nuova connessione e autorizzazioni correnti; il recupero legge lo stato confermato senza rieseguire il lavoro.

Accettazione del rilascio

L'audit di sicurezza e la validazione delle vulnerabilità sono in sospeso in seguito al rinvio del proprietario del 2026-10-05. I risultati funzionali, di compatibilità e prestazioni non costituiscono un'accettazione di sicurezza. La revisione conservata riprenderà separatamente; questo rilascio non deve essere descritto come se avesse superato quell'audit.

La fixture combinata esercita contemporaneamente linguaggio/impostazioni, modifiche revisionate, job di comandi, osservazione del progetto, upload/download e archiviazione conservata. Verifica interruzioni, risposte malformate, revoche, cambi di generazione, recupero e pulizia delle risorse. Test separati di filesystem/processi coprono processi figli terminati, corruzione, scritture fallite, scadenza e annullamento ignorato. Il report di accettazione RC collega comandi riproducibili e i limiti di ogni risultato.

Le misure di prestazioni registrano cinque campioni in nuovi processi per ogni profilo Windows/Linux e Node 22/24, includendo mediana/dispersione, tempo CPU, memoria campionata, tempi di importazione/avvio/osservazione e conteggi logici dei payload su disco/HTTP. Le soglie di riferimento derivano da questi campioni misurati e sono controlli grossolani delle regressioni, non uno SLA di latenza. Non misurano il traffico fisico su disco né garantiscono l'individuazione di ogni handle del sistema operativo.

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à · Inventario delle API · Politica di supporto · Accettazione RC

Contenuti del rilascio stabile 1.0

Il pacchetto originale 1.0 comprende 38 esportazioni e 86 schemi con dichiarazioni, esempi, LICENSE e NOTICE. La 1.1 aggiunge gli strumenti di rilascio riportati sotto; la 1.2 aggiunge le sezioni su workflow/cache/strumenti/LSP riportate sotto. Le ricevute di rilascio distinguono sorgenti/CI/digest esatti, nuovi consumer e prove browser riutilizzate.

Per tornare a una versione precedente, interrompi il lavoro di proprietà e seleziona esplicitamente archivi SDK/plugin compatibili conservati e un'esportazione della configurazione. Rivedi le autorizzazioni correnti e crea una nuova connessione. Il recupero dei risultati è solo in lettura; effetti esterni e impostazioni incompatibili non vengono annullati automaticamente. Verifica i formati e le funzionalità opzionali effettivamente usati.

Contenuti del rilascio, migrazione e supporto

Bundle offline e SBOM

L'SDK 1.1 aggiunge cinque punti di ingresso opzionali solo per Node: /bundles, /provenance, /updates, /updates-node e /upstream. Il pacchetto contiene 43 esportazioni, 96 schemi, dichiarazioni ed esempi eseguibili senza dipendenze npm di runtime. Le API 1.0 esistenti e gli archivi DDS .tgz non firmati restano compatibili.

lockBundleDependency vincola un albero di file ESM/CommonJS revisionato a una versione esatta, una fonte HTTPS, un digest canonico dei file, una mappa delle dipendenze, LICENSE/NOTICE e una decisione esplicita sulla redistribuzione. Il digest descrive l'albero revisionato; non è l'hash di un archivio upstream. createPluginBundle incorpora l'archivio originale del plugin DDS e i metadati di rilascio, un grafo aciclico di dipendenze a versione unica e una SBOM deterministica CycloneDX 1.6.

verifyPluginBundle verifica lo snapshot esatto dei byte entro i limiti previsti. installPluginBundle richiede expectedSha256, approved: true e una nuova directory sotto una directory padre di proprietà dell'operatore. Non esegue npm, script del ciclo di vita, download o codice del plugin. Le dipendenze non ereditano nuove autorizzazioni. L'SDK dell'host è una dipendenza separata. Addon nativi, mappe di esportazione e risoluzione arbitraria di dipendenze npm sono fuori da questo formato.

Limiti: 32 pacchetti di dipendenze, 1.024 file espansi, 4 MiB per file di dipendenza, 32 MiB di contenuto espanso e 48 MiB di bundle codificato. L'archivio radice originale ha limiti propri più ridotti. Vengono rifiutati versioni mancanti o in conflitto, cicli, dipendenze orfane, hash modificati, licenze/NOTICE mancanti, percorsi/collegamenti e collisioni tra file e directory. Le installazioni fallite conservano la nuova destinazione per l'ispezione. Escludi scritture concorrenti; questo strumento non è una sandbox del sistema operativo.

Firme separate e fiducia dell'operatore

createProvenanceStatement lega nome/versione/SHA-256 esatti del bundle, editore, revisione sorgente e date di emissione/scadenza. signPluginProvenance usa un Ed25519 KeyObject di proprietà del chiamante. canonicalProvenancePayload espone DDS-PROVENANCE-V1 seguito da JSON canonico, così un altro firmatario può riprodurre lo stesso payload. L'SDK non fornisce chiavi private di firma né autorità di firma del prodotto DDS.

verifyPluginProvenance riceve radici di fiducia selezionate dall'operatore, associazioni editore/soggetto, ora corrente, validità/revoca delle chiavi e prove di revoca con timestamp. La verifica offline usa le prove fornite e applica lo stesso limite di freschezza; non recupera mai da sola informazioni di revoca aggiornate. Una nuova chiave di pacchetto non è fidata finché l'operatore non la aggiunge. Radici sovrapposte esplicite supportano la rotazione. Lo scarto massimo dell'orologio è di cinque minuti e l'età massima delle prove è di 30 giorni; scegli limiti più severi se necessario.

Le ricevute mantengono separati checksum, firma, editore e politica e restituiscono sempre executionAuthorized: false. Una firma non dimostra la sicurezza del codice né concede autorità di esecuzione, accesso ai dati o sandbox. I vecchi pacchetti non firmati richiedono envelope: null e allowUnsigned: true, continuando a indicare assenza di firma ed editore non verificato. L'audit di sicurezza e la validazione delle vulnerabilità restano separatamente in sospeso.

Revisione, attivazione e ripristino

createPluginUpdatePlan confronta versione vecchia/nuova, API, autorizzazioni, fonti/hash delle dipendenze, strumenti dichiarati, licenze, hash delle impostazioni, identità della migrazione, firma e chiave, quindi fissa il digest di revisione. createPluginUpdateController gestisce host e impostazioni attualmente autorizzati e le porte getPolicy/prepare dell'operatore. Stage verifica e acquisisce uno snapshot del candidato; approve deve corrispondere al digest esatto del piano, alle autorizzazioni e all'ID della chiave. Activate verifica le impostazioni correnti e aggiorna la fiducia prima e dopo la preparazione di un host candidato separato.

wait rinvia l'attivazione durante l'esecuzione dei job. retain-old lascia i vecchi job su host/impostazioni/hash originali e invia le nuove esecuzioni al nuovo host dopo il passaggio. execute restituisce l'hash del plugin insieme a ogni risultato. I job non vengono annullati implicitamente. La sostituzione delle impostazioni invalida un'approvazione in sospeso; cambiamenti concorrenti e preparazione fallita preservano o segnalano esplicitamente lo stato precedente. Il rollback prepara il vecchio pacchetto con le impostazioni come un nuovo aggiornamento revisionato e richiede fiducia corrente e una nuova approvazione.

Preparazione e migrazioni passano attraverso porte fidate di proprietà dell'operatore. Né rollback né errore annullano file esterni, richieste di rete o altri effetti. reversible è un metadato di revisione, non una promessa di annullamento automatico. Un journal Node è a sola aggiunta, con un solo writer e fuori dal workspace, con CAS sulla revisione esatta e limiti di 256 record / 128 KiB per envelope / 8 MiB totali. Al raggiungimento del limite, archivialo sotto il controllo dell'operatore prima di aprire un nuovo journal.

inspectNodeUpdateJournal legge lo stato persistito senza riproduzione. Un crash durante preparing o una conferma ambigua richiedono una rilettura esplicita di host/impostazioni; reconcilePluginUpdateJournal registra un digest vecchio/nuovo noto e approvato e l'hash delle impostazioni. Le code corrotte richiedono ispezione/riparazione dell'operatore. recoverStaleLock recupera solo un writer sulla stessa macchina di cui sia stata dimostrata la terminazione. Non promette una transazione di host/impostazioni tra processi né atomicità universale in caso di perdita di alimentazione.

Verifiche upstream esplicite e candidati

fetchUpstreamArtifact necessita di invocazione esplicita, enabled: true, URL/versione/digest esatti della fonte, elenco esatto di URL consentiti, politica offline, budget di byte e scadenza. Anche le destinazioni dei reindirizzamenti devono essere consentite. Non invia cookie né header di autenticazione, non riprova automaticamente e segnala verified / digest-mismatch / unavailable / offline / unverified con l'ora dell'osservazione. Tag o hash cambiati richiedono una nuova revisione. HTTP su loopback è disponibile solo tramite un'opzione esplicita per fixture.

Gli adattatori possono pubblicare un upstream-manifest revisionato contenente inventario delle API, revisione sorgente esatta, licenza/NOTICE completi e hash dei file. inspectUpstreamManifest collega quei metadati ai byte scaricati; non analizza codice sorgente arbitrario né deduce permessi di redistribuzione. createUpstreamCandidate restituisce differenze di API/file/licenze e una patch con digest precedente/fonte sostitutiva. La corrispondenza a una matrice esatta di versioni senza una verifica funzionale dello sviluppatore resta non verificata; un'API richiesta assente risulta non supportata.

Anche un candidato supportato richiede una revisione umana. Il suo array automaticActions è vuoto; queste API non creano branch, non eseguono merge, non pubblicano, non approvano nuove autorizzazioni né installano un monitor. L'host gestisce esecuzione e annullamento dei test degli adattatori. L'esempio pubblico completo qui sotto usa solo fixture locali. Le API per workflow/cache/strumenti/LSP sono disponibili nelle sezioni 1.2 qui sotto.

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

Tipi, API, limiti e sorgenti completi eseguibili

Flussi di comandi e recupero esplicito

L'SDK 1.2 aggiunge sette esportazioni opzionali: /workflows, /workflows-node, /workflow-cache, /workflow-cache-node, /tool-streams, /tool-streams-node e /lsp-node. Il pacchetto attuale ha 50 esportazioni, 107 schemi, dichiarazioni TypeScript ed esempi installati indipendenti, senza dipendenze npm di runtime. Solo /tool-streams è portabile nel browser; le altre nuove esportazioni richiedono Node. Il protocollo workspace esistente e le API 1.x restano compatibili. Un plugin che importa una nuova API 1.2 deve dichiarare 1.2.0 come versione minima dell'SDK.

prepareWorkflowPlan valida ID dei comandi registrati, passi univoci, dipendenze acicliche, schemi chiusi dei dati di input/output e collegamenti richiesti degli output prima dell'esecuzione. Ogni input è un valore letterale {value} o un collegamento {step, path} a una dipendenza esplicita. I vincoli degli schemi devono corrispondere esattamente. Il piano immutabile lega comandi, autorizzazioni, ambito e input a uno SHA-256. run richiede approved: true e quel digest esatto revisionato. Le porte authorize ed execute dell'host restano di proprietà dell'operatore.

createCommandJobExecutor collega un PluginHost esistente isolato selezionato da resolveHost, che restituisce ambito esatto dell'host, autorizzazioni del passo e hash del plugin. Le autorizzazioni non vengono mai combinate tra passi. L'autorizzazione corrente è verificata prima dell'esecuzione, dopo i risultati e prima del riutilizzo. continue completa i rami indipendenti e blocca i discendenti falliti; fail-fast annulla i passi rimanenti. I record conservano ID di job/tentativi padre, job individuali, digest di input/output, artefatti, motivi e timestamp. I risultati trovati in cache non hanno un nuovo ID job e non possono dichiarare artefatti mutabili dei job.

recover legge un checkpoint archiviato e segnala il lavoro in sospeso/in esecuzione come interrotto, senza eseguirlo. Una ripresa manuale fornisce il record precedente esatto e previousAttemptId in una nuova approvazione, crea un nuovo tentativo e conserva solo risultati riusciti corrispondenti e non scaduti. retrySteps riesegue i passi selezionati e i relativi discendenti anche in un DAG non ordinato. Un output scaduto richiede la selezione esplicita di un nuovo tentativo; cambiamenti a schema, input, autorizzazioni o hash del plugin richiedono un nuovo piano. Un executor che ignora l'annullamento continua a essere conteggiato come non terminato e impedisce tentativi sovrapposti.

createNodeWorkflowStore usa directory reali e separate per store/workspace, ambito e marcatori di identità del filesystem, un solo writer, envelope con checksum e checkpoint CAS. Dopo un crash noto, recoverStaleLock esplicito accetta solo un proprietario sulla stessa macchina di cui sia stata dimostrata la terminazione. La pulizia predefinita gestisce record corrotti riconosciuti e scritture incomplete preservando file/collegamenti sconosciuti. cleanup({expiredBefore}) può anche rimuovere record terminali scaduti; quelli attivi restano per il recupero. Su Windows non viene dichiarato fsync delle directory né persistenza in caso di perdita di alimentazione. Limiti: 64 passi, 8 passi simultanei, scadenza del workflow di 10 minuti, 64 KiB per risultato, 1 MiB di output combinati, record di 2 MiB, 64 record conservati e conservazione di risultati parziali per al massimo 24 ore.

Tipi, API, limiti ed esempi completi eseguibili

Cache deterministica ed esecuzione incrementale

fingerprintWorkflowInputs calcola hash dei byte effettivi dei file insieme a versione SDK, ambito workspace/sicurezza, schema/input del comando, hash di plugin/strumenti, impostazioni, ambiente dichiarato e autorizzazioni. mtime e percorso da soli non sono mai identità del contenuto. L'operatore dichiara esplicitamente optIn, deterministic, declaredInputsComplete e secretDependent. Input sconosciuti o incompleti, non determinismo, dipendenza da segreti, ambiente mancante/non dichiarato e input con riferimenti a segreti saltano la cache indicando il motivo. L'host deve inoltre escludere segreti grezzi ed effetti collaterali; l'SDK non può dedurre input nascosti.

createWorkflowCache riverifica l'autorizzazione corrente durante lookup/fill/after-fill/hit/return e verifica hash dei valori, ambito, autorizzazioni e scadenza. Miss simultanei idonei condividono un unico fill; annullare un'attesa non annulla le altre. Valori scaduti o danneggiati sono miss. TTL/LRU, budget di voci/valori e pulizia dello store di proprietà controllano l'archiviazione; scritture fallite restano risultati calcolati con un motivo esplicito. I risultati con riferimenti a segreti non vengono mai conservati. I limiti delle impronte sono 64 file, 4 MiB ciascuno e 16 MiB totali; quelli della cache sono 512 voci, 16 MiB di byte di valori conservati, otto fill e 60 secondi per fill.

L'esempio di workflow consulta la cache solo dopo il successo delle dipendenze correnti. Un file modificato invalida il suo passo; output modificati invalidano le impronte degli input dipendenti. Una dipendenza fallita blocca il padre prima di cercare un risultato del padre in cache. Le ricevute distinguono hit, miss, shared e bypass, esecuzione effettiva e riutilizzo, contatori della cache, byte archiviati e tempi locali. Lo stato persistente della cache usa directory separate del proprietario e sostituzione atomica, con recupero di scritture orfane/corruzione; non elimina file sorgente.

Tipi, API, limiti ed esempi completi eseguibili

Flussi di output degli strumenti registrati

createToolStreamParser è un decoder portabile UTF-8 JSONL/testo con limiti definiti. Attendi write(bytes, stdout/stderr) per la contropressione e termina solo dopo la fine di entrambi i flussi. Preserva caratteri multibyte divisi e righe parziali finali, emettendo eventi correlati di log, avanzamento, diagnostica e sconosciuti. UTF-8 malformato e limiti rigidi interrompono il parsing. Vengono validati percorsi diagnostici relativi, posizioni ordinate e gravità; l'editor consumer deve validare anche le posizioni rispetto al testo corrente del documento. createJobToolEventSink collega avanzamento/log a un JobReporter esistente e lascia la diagnostica a un sink di proprietà del chiamante.

Il runner Node opzionale accetta registrazioni fisse dell'operatore: backend/strumento/versione, eseguibile assoluto e vincoli su implementazioni selezionate, probe della versione esatta, ambiente esplicito, schema di input chiuso e slot richiesti per argomenti scalari. Gli slot dei file devono indicare file workspace relativi esistenti. L'invocazione di un plugin seleziona solo uno strumento/versione già registrato e input validato; non può scegliere una shell o un eseguibile. L'autorizzazione corrente è verificata prima di preparazione/avvio, durante gli eventi e dopo il completamento. Le ricevute conservano codice di uscita, motivo di annullamento/errore e statistiche degli output.

I valori letterali noti di segreti/percorsi su una singola riga vengono mascherati dopo l'assemblaggio della riga, anche se divisi in blocchi; i segreti codificati o sconosciuti non vengono rilevati automaticamente. Il runner possiede solo il figlio diretto e le relative pipe e li chiude in caso di annullamento o chiusura. Non analizza né termina alberi di processi estranei o discendenti e non è una sandbox del sistema operativo. Limiti: blocchi di 64 KiB, righe di 16 KiB, output totale di 2 MiB, 4.096 eventi, otto scritture in coda, sink di cinque secondi, 32 strumenti e quattro esecuzioni simultanee. Un probe separato di cinque secondi/16 KiB verifica la versione configurata.

La fixture redistribuibile dello strumento scritta dall'SDK verifica UTF-8/JSONL frammentato, output finale, uscite non nulle, annullamento e limiti. L'adattatore effettivo è TypeScript 5.9.3 con --noEmit --noLib --pretty false e una fixture temporanea di tipi intrinseci che produce TS2322. Per eseguirlo, fornisci esplicitamente una radice TypeScript approvata esistente. L'SDK non installa né scarica mai automaticamente uno strumento esterno; gli hash forniti non autenticano in modo indipendente il suo editore.

Tipi, API, limiti ed esempi completi eseguibili

Bridge LSP stdio pubblico

createLspBridge collega un processo stdio vincolato e approvato esplicitamente alle richieste/provider di linguaggio SDK esistenti. Negozia il sottoinsieme supportato di LSP 3.17, posizioni UTF-16 e snapshot completi. capabilities segnala il supporto dichiarato separatamente dalle esecuzioni riuscite. Le mappature supportate coprono completamento, hover, definizione, riferimenti, simboli piatti/gerarchici, assistenza alle firme, prepare-rename/rename, formattazione di documenti/intervalli, azioni sul codice, token semantici completi, folding e inlay hint: 15 funzionalità SDK.

syncDocument e closeDocument gestiscono didOpen/didChange/didClose. Cambiamenti alla versione e alla generazione correnti annullano il lavoro obsoleto, gli ID duplicati di richieste attive vengono rifiutati e le risposte tardive ignorate. Gli URI locali devono risolversi all'interno del workspace senza collegamenti; sorgenti e destinazioni delle modifiche richiedono autorizzazione corrente e uno snapshot esatto aperto o fornito dall'host. I risultati di rinomina/formattazione/azioni sono proposte condizionate di modifica del workspace con hash di base, mai modifiche applicate automaticamente o comandi eseguibili.

La diagnostica è accettata solo con la versione corrente del documento. Le notifiche senza versione/obsolete vengono scartate e conteggiate. Le funzionalità esplicitamente non supportate sono completion resolve/snippet, code-action resolve, delta semantici, comandi server, capacità dinamiche, operazioni sulle risorse, trasporti socket e diagnostica senza versione. workspace/applyEdit restituisce applied:false. Limiti: messaggi di 1 MiB, header di 8 KiB, sessioni di 64 MiB/20.000 messaggi, 16 richieste in sospeso e scritture in coda, 32 documenti/4 MiB di testo aggregato, scadenze delle richieste fino a 30 secondi e 64 KiB di stderr scartato.

close invia shutdown/exit ed esegue la pulizia limitata di processo diretto/pipe, distinguendo conferma regolare, server che rifiutano o subiscono crash e chiusura effettiva del processo. Un server può confermare shutdown e richiedere comunque l'arresto del processo di proprietà. Non ci sono riavvio o riproduzione automatici: l'operatore crea un nuovo bridge e reinvia esplicitamente gli snapshot correnti selezionati. I test sintetici coprono framing malformato, crash/timeout, annullamento/risposte tardive, condizioni di gara sui documenti, shutdown rifiutato, richieste non supportate e ogni funzionalità mappata.

La verifica effettiva del server indipendente usa typescript-language-server 5.3.0 della comunità con TypeScript 5.9.3: completamento, hover, definizione, riferimenti, simboli, assistenza alle firme, formattazione e token semantici hanno superato i test. File di implementazione selezionati e Node sono vincolati, il percorso di tsserver è fisso e l'acquisizione automatica dei tipi è disabilitata. Questa versione del server omette initialize.serverInfo opzionale e invia diagnostica senza versione, quindi la sua diagnostica è esplicitamente non supportata da questo bridge; quella versionata è verificata usando il server sintetico indipendente. L'operatore deve fidarsi dell'intero strumento installato e del suo accesso al sistema operativo.

L'accettazione della 1.2 comprende consumer impacchettati indipendenti, dichiarazioni, 107 schemi, gli adattatori effettivi di compilatore/server e interoperabilità con archivi pubblici storici. L'esempio di workflow distingue il recupero persistente e il nuovo tentativo esplicito dalla riproduzione automatica. L'audit di sicurezza e la validazione delle vulnerabilità restano in sospeso per il rinvio del proprietario. Questo rilascio non costituisce un'accettazione di DDS UI, Engine, scheduler Cloud, Marketplace, installer o sandbox di sicurezza.

Tipi, API, limiti ed esempi completi eseguibili

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

Per gli adattatori effettivi, aggiungi percorsi assoluti a installazioni esistenti approvate dall'operatore. Gli esempi predefiniti usano solo fixture scritte dall'SDK e non scaricano mai uno strumento.

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