Desarrollo y versiones del Plugin SDK

Desarrollo, verificación, herramientas de publicación y flujos de trabajo 1.2, caché incremental, herramientas externas y puente LSP público.

Guía de desarrollo, verificación y publicación de DDS Plugin SDK 1.2.0. La auditoría de seguridad y la validación de vulnerabilidades están pendientes; el estado estable de la API y las comprobaciones funcionales no constituyen una aceptación de seguridad.

Guía de instalación del SDK y de la API

Plantillas de desarrollo y generación

Elige comando, lenguaje, tema, trabajo, navegador o configuración. init --dry-run informa del destino, el inventario de archivos, los hashes y los conflictos sin escribir ni instalar. Un init normal requiere un directorio real nuevo. Cada plantilla incluye código fuente, manifiesto, declaración de información, licencia/aviso, pruebas, un consumidor con tipos y un ejemplo ejecutable. Las plantillas de navegador y configuración incluyen una demostración de loopback. Las dependencias generadas fijan el archivo exacto de GitHub.

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 datos JSON acotados para esquemas de comandos, ajustes, catálogos de idiomas y datos de temas. generate emite JSON de ejecución, exportaciones ESM, tipos TypeScript de entrada sin validar y validados, tipos de salida/ajustes, JSON Schema y XML de temas. Los valores predeterminados de JSON Schema son anotaciones; solo la validación de entradas del SDK aplica esos valores. La generación no importa tu plugin. doctor comprueba desviaciones, metadatos, módulos ausentes y si los archivos de ejecución generados están incluidos en la lista de archivos permitidos del paquete.

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 sustitución requiere el resumen criptográfico anterior exacto y que los bytes generados no hayan cambiado. Las modificaciones manuales, los archivos adicionales, los enlaces y los bloqueos obsoletos detienen la sustitución. Ante un fallo, solo se eliminan las entradas sin modificar que pertenecen a ese intento; las entradas modificadas o de estado incierto se conservan para su inspección. El límite es de 256 archivos, 1 MiB por archivo y 4 MiB en total. El bloqueo coordina generadores cooperativos; no protege frente a un escritor hostil concurrente en el sistema de archivos ni proporciona una transacción atómica entre directorios. Las plantillas propietarias requieren condiciones aportadas por el llamador y conservan los archivos de licencia/aviso heredados del SDK.

Pruebas deterministas y reproducción

createScenarioHost de /testing monta explícitamente los fixtures seleccionados de archivos en memoria, backend, ajustes, secretos y trabajos. Comienza sin permisos concedidos ni capacidades. createTestClock proporciona identificadores, tiempo y temporizadores a partir de una semilla sin modificar los objetos globales; los temporizadores con la misma hora conservan el orden de inserción. Espera el avance del reloj para desbloquear las esperas virtuales. Los UUID generados son datos de prueba, no entropía criptográfica. Los valores predeterminados existentes de createTestHost siguen siendo 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();
}

Los puertos de fallos modelan retrasos, denegaciones, desconexiones, corrupción, agotamiento y llamadas descartadas; los fixtures de eventos pueden descartarse, duplicarse o invertirse sin repetir efectos externos. replaceGrants desactiva los plugins que pierden autorización. Las instantáneas de trabajos en memoria validan identidad, revisión y hashes, y modelan la recuperación interrumpida sin ejecución automática. Estos fixtures no emulan la durabilidad del sistema de archivos ni descubren identificadores de recursos del sistema operativo. Un registro de propiedad separado sigue los recursos registrados explícitamente. La limpieza conserva los recuentos pendientes de los callbacks que ignoran la cancelación hasta que realmente finalizan. Ahora se puede leer inspect de los ajustes después de liberar los recursos; las lecturas de datos siguen rechazándose.

La grabación requiere synthetic: true y un inventario explícito y acotado de fixtures. Las trazas exportadas contienen solo tipos de operación, identificadores de fixtures, tiempos, semilla/versión y hashes encadenados. Usa identificadores sin información sensible; los hashes no anonimizan datos que puedan adivinarse, y el SDK no puede clasificar entradas arbitrarias como sintéticas. La reproducción pura comprueba el orden, los hashes y la identidad de los fixtures y devuelve las salidas seleccionadas de estos; no acepta callbacks de efectos. Los límites incluyen 64 fixtures, 1.024 eventos y una traza de 1 MiB. Ejecuta el ejemplo development-tools incluido en el paquete para comprobar fallos, recuperación, privacidad y limpieza.

Diagnóstico local y depuración

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

El diagnóstico está desactivado de forma predeterminada y es exclusivamente local. Los informes contienen códigos fijos de operación/estado/error, identificadores de correlación, duraciones y recuentos de recursos; no hay una API para cuerpos de documentos, rutas, entradas, cuerpos de salida ni texto arbitrario de excepciones. Los recuentos de bytes, la profundidad de las colas y las cifras de memoria son estimaciones explícitas del responsable. profileTransport mide hasta que se resuelve la llamada envuelta; en fetch, esto corresponde a las cabeceras de respuesta y no a la finalización del cuerpo. Los registros completos usan un búfer circular acotado y caducidad pasiva; no hay temporizadores de diagnóstico en segundo plano ni subidas. Los valores predeterminados son 128 eventos/60 segundos; los máximos son 256 eventos/5 minutos, 64 spans en curso y 256 KiB por informe.

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

El modo de depuración expone únicamente un inspector efímero en 127.0.0.1 dentro del proceso hijo bajo su control. --debug-wait pausa antes de importar el plugin y requiere --debug. El presupuesto total de ejecución incluye la espera del depurador y es de 30 segundos como máximo. La finalización, la cancelación y el tiempo de espera terminan el proceso hijo controlado y el inspector. Tanto el perfilado como la depuración requieren confianza explícita en el código local; ninguno constituye un entorno aislado. Los fallos o la terminación forzada pueden impedir que se emita el informe de perfil, y el stdout/stderr bruto del plugin sigue siendo un flujo separado y acotado que no se censura automáticamente.

Herramientas de desarrollo · Pruebas · Diagnóstico · Compatibilidad

Conformidad del host

El módulo /conformance ejecuta sondas sintéticas versionadas contra los adaptadores de host, ajustes, espacio de trabajo, localización, pruebas, diagnóstico y desarrollo que proporciones explícitamente. Distingue perfiles compatibles, no compatibles y fallidos, e incluye host/versión/runtime/plataforma, identificador de comprobación, tiempos y limpieza. Una función declarada cuyo adaptador falte o esté roto falla; las funciones opcionales desconocidas se registran sin sondearlas. Los comandos, los permisos y la cancelación son obligatorios de forma predeterminada.

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

Sustituye la fábrica del host por tu adaptador y ejecuta también las pruebas de tu plugin. El asistente Node /conformance-node solo crea fixtures temporales nuevos y servidores loopback efímeros. El ejemplo de navegador ejecuta los perfiles de navegador disponibles y marca las funciones de Node ausentes como no compatibles. Las sondas rápidas muestrean contratos; los ejemplos enlazados y las pruebas de publicación cubren rutas más amplias de lenguaje, recuperación y almacenamiento. Un informe es evidencia de pruebas, no un certificado de confianza.

Los plazos predeterminados son de 10 segundos por caso y como máximo de 30 segundos. Un tiempo de espera agotado o una cancelación detiene los casos posteriores; un fallo de limpieza hace fallar el caso, y la limpieza pendiente queda sin verificar. Los adaptadores de confianza dentro del proceso pueden bloquear de forma síncrona y conservar la autoridad del entorno. Los informes excluyen cuerpos de errores de proveedores, cargas útiles, tokens y rutas; elige etiquetas de identidad sin información sensible. Ningún informe se sube automáticamente.

Soporte y migración del SDK

API_SUPPORT.json enumera todos los módulos exportados, nombres de ejecución, declaraciones, resúmenes criptográficos de declaraciones, entornos y estados de estabilidad. Las API estables 1.x siguen el versionado semántico: las adiciones compatibles usan una versión menor y los cambios estables incompatibles requieren una nueva versión mayor. artifact-resume-browser sigue siendo experimental y necesita una versión exacta del SDK/navegador con una aceptación nueva en navegador. Siguen siendo necesarios el descubrimiento de capacidades opcionales y los permisos actuales.

La política de la línea estable se aplica desde 1.0.0. La última versión menor estable recibe correcciones ordinarias; la versión menor anterior sigue siendo elegible para correcciones de seguridad críticas durante 90 días en un runtime admitido. Ninguna API estable queda obsoleta en 1.0.0. Las retiradas se anuncian durante al menos dos versiones menores y seis meses antes de eliminarlas en una versión mayor. Las RC y las versiones preliminares quedan reemplazadas. Esta política de código abierto no promete tiempos de respuesta comerciales.

La aceptación de servidor y CLI cubre Windows/Linux con Node 22 o 24 actualizado y declaraciones con TypeScript 5.9.3. El soporte de Node 22 termina el 2027-04-30 y el de Node 24 el 2028-04-30. Los comprobantes de publicación identifican las versiones exactas de parche, las imágenes del sistema operativo y la compilación del navegador. Otros runtimes y combinaciones de navegador/almacenamiento necesitan su propia aceptación. Las dependencias npm de ejecución del SDK siguen estando vacías.

Los plugins estables 1.0 usan >=1.0.0 <2.0.0; eleva el mínimo al adoptar una API posterior. Los paquetes RC1 conservan su peer exacto 1.0.0-rc.1. Para cambiarlo, vuelve a validar y publica una nueva versión del plugin; conserva inmutables los archivos anteriores. Los archivos heredados son entradas para interoperabilidad, no líneas mantenidas. Después de reiniciar, establece una nueva conexión y permisos actuales; la recuperación lee el estado confirmado sin volver a ejecutar el trabajo.

Aceptación de la versión

La auditoría de seguridad y la validación de vulnerabilidades están pendientes conforme al aplazamiento del responsable del 2026-10-05. Los resultados funcionales, de compatibilidad y de rendimiento no constituyen una aceptación de seguridad. La revisión conservada se reanudará por separado; no debe describirse esta versión como aprobada en esa auditoría.

El fixture combinado ejercita simultáneamente lenguaje/ajustes, ediciones revisadas, trabajos de comandos, seguimiento del proyecto, subida/descarga y almacenamiento retenido. Comprueba interrupciones, respuestas malformadas, revocación, cambios de generación, recuperación y limpieza de recursos. Las pruebas separadas de sistema de archivos/procesos cubren hijos terminados, corrupción, escrituras fallidas, caducidad y cancelación ignorada. El informe de aceptación RC enlaza comandos reproducibles y los límites de cada resultado.

El rendimiento registra cinco muestras con procesos nuevos por perfil Windows/Linux y Node 22/24, incluyendo mediana/dispersión, tiempo de CPU, memoria muestreada, tiempos de importación/inicio/seguimiento y recuentos lógicos de cargas útiles de disco/HTTP. Los umbrales de referencia proceden de esas muestras medidas y son protecciones aproximadas contra regresiones, no un SLA de latencia. No miden el tráfico físico del disco ni garantizan que se descubra cada identificador de recurso 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

Conformidad · Inventario de API · Política de soporte · Aceptación RC

Contenido de la versión estable 1.0

El paquete original 1.0 incluye 38 exportaciones y 86 esquemas con declaraciones, ejemplos, LICENSE y NOTICE. 1.1 añade las herramientas de publicación que se describen más abajo; 1.2 añade las secciones de flujos de trabajo/caché/herramientas/LSP siguientes. Los comprobantes de publicación distinguen el código fuente/CI/resúmenes criptográficos exactos, los consumidores nuevos y la evidencia reutilizada del navegador.

Para volver a una versión anterior, detén el trabajo bajo tu control y selecciona explícitamente archivos retenidos y compatibles del SDK/plugin y una exportación de configuración. Revisa los permisos actuales y crea una conexión nueva. La recuperación de resultados solo lee el estado; los efectos externos y los ajustes incompatibles no se deshacen automáticamente. Prueba los formatos y las funciones opcionales que realmente utilices.

Contenido de la versión, migración y soporte

Paquetes sin conexión y SBOM

SDK 1.1 añade cinco puntos de entrada opcionales exclusivos de Node: /bundles, /provenance, /updates, /updates-node y /upstream. El paquete contiene 43 exportaciones, 96 esquemas, declaraciones y ejemplos ejecutables, sin dependencias npm de ejecución. Las API 1.0 existentes y los archivos DDS .tgz sin firma siguen siendo compatibles.

lockBundleDependency fija un árbol de archivos ESM/CommonJS revisado a una versión exacta, una fuente HTTPS, un resumen criptográfico canónico de archivos, un mapa de dependencias, LICENSE/NOTICE y una decisión explícita de redistribución. El resumen describe el árbol revisado; no es el hash de un archivo del proyecto de origen. createPluginBundle incorpora el archivo original del plugin DDS y sus metadatos de publicación, un grafo acíclico de dependencias con una sola versión y una SBOM determinista CycloneDX 1.6.

verifyPluginBundle comprueba la instantánea exacta y acotada de bytes. installPluginBundle requiere su expectedSha256, approved: true y un directorio nuevo bajo un directorio padre propiedad del operador. No ejecuta npm, scripts del ciclo de vida, descargas ni código del plugin. Las dependencias no heredan permisos nuevos. El SDK del host es una dependencia separada. Los complementos nativos, los mapas de exportación y la resolución arbitraria de dependencias npm quedan fuera de este formato.

Límites: 32 paquetes de dependencias, 1.024 archivos expandidos, 4 MiB por archivo de dependencia, 32 MiB de contenido expandido y 48 MiB de paquete codificado. El archivo raíz original tiene sus propios límites menores. Se rechazan versiones ausentes o en conflicto, ciclos, dependencias huérfanas, hashes cambiados, licencias/NOTICE ausentes, rutas/enlaces y colisiones entre archivos y directorios. Las instalaciones fallidas conservan el destino nuevo para inspección. Excluye escritores concurrentes; esta herramienta no es un entorno aislado del sistema operativo.

Firmas separadas y confianza del operador

createProvenanceStatement vincula el nombre/versión/SHA-256 exactos del paquete, el editor, la revisión del código fuente y las horas de emisión/caducidad. signPluginProvenance utiliza un KeyObject Ed25519 propiedad del llamador. canonicalProvenancePayload expone DDS-PROVENANCE-V1 seguido de JSON canónico para que otro firmante pueda reproducir la misma carga útil. El SDK no suministra una clave privada de firma ni autoridad para firmar productos DDS.

verifyPluginProvenance toma raíces de confianza seleccionadas por el operador, vínculos de editor/sujeto, la hora actual, validez/revocación de claves y evidencia de revocación con marcas de tiempo. La verificación sin conexión utiliza la evidencia aportada y aplica el mismo margen de vigencia; nunca obtiene por sí misma información nueva sobre revocación. Una clave de paquete nueva no es de confianza hasta que el operador la añade. Las raíces explícitas superpuestas permiten la rotación. El desfase máximo del reloj es de cinco minutos y la antigüedad máxima de la evidencia es de 30 días; selecciona límites más estrictos cuando sea necesario.

Los comprobantes mantienen separados checksum, firma, editor y política, y siempre devuelven executionAuthorized: false. Una firma no demuestra la seguridad del código ni concede autoridad de ejecución, acceso a datos o aislamiento. Los paquetes antiguos sin firma requieren envelope: null y allowUnsigned: true, y siguen indicando ausencia de firma y editor no verificado. La auditoría de seguridad y la validación de vulnerabilidades continúan pendientes de forma independiente.

Revisión, activación y reversión

createPluginUpdatePlan compara versiones antigua/nueva, API, permisos concedidos, fuentes/hashes de dependencias, herramientas declaradas, licencias, hashes de ajustes, identidad de migración, firma y clave, y después fija el resumen criptográfico de la revisión. createPluginUpdateController controla el host autorizado y los ajustes actuales, además de los puertos getPolicy/prepare del operador. Stage verifica y crea una instantánea del candidato; approve debe coincidir con el resumen exacto del plan, los permisos y el identificador de clave. Activate comprueba los ajustes actuales y actualiza la confianza antes y después de preparar un host candidato separado.

wait aplaza la activación mientras haya trabajos en ejecución. retain-old deja los trabajos antiguos en su host/ajustes/hash originales y envía las nuevas ejecuciones al host nuevo tras el cambio. execute devuelve el hash del plugin junto a cada resultado. Los trabajos no se cancelan implícitamente. Sustituir los ajustes invalida una aprobación pendiente; los cambios concurrentes y la preparación fallida conservan o informan explícitamente del estado anterior. La reversión prepara el paquete/ajustes antiguos como una nueva actualización revisada y requiere confianza actual y aprobación nueva.

La preparación y las migraciones se ejecutan a través de puertos de confianza propiedad del operador. Ni una reversión ni un fallo deshacen archivos externos, solicitudes de red u otros efectos. reversible es un metadato de revisión, no una promesa de deshacer automáticamente. Un diario Node es de solo anexado, tiene un único escritor y está fuera del espacio de trabajo, con CAS de revisión exacta y límites de 256 registros / 128 KiB por sobre / 8 MiB en total. Archívalo bajo control del operador antes de abrir un diario nuevo al llegar al límite.

inspectNodeUpdateJournal lee el estado persistido sin reproducirlo. Un fallo durante preparing o una confirmación ambigua requiere una lectura explícita del host/ajustes; reconcilePluginUpdateJournal registra un resumen antiguo/nuevo conocido y aprobado y el hash de ajustes. Las colas corruptas requieren inspección/reparación del operador. recoverStaleLock solo recupera un escritor de la misma máquina cuya terminación esté demostrada. Esto no promete una transacción de host/ajustes entre procesos ni atomicidad universal ante pérdida de alimentación.

Comprobaciones explícitas del proyecto de origen y candidatos

fetchUpstreamArtifact requiere una invocación explícita, enabled: true, URL/versión/resumen criptográfico exactos de origen, lista exacta de URL permitidas, política sin conexión, presupuesto de bytes y plazo. Los destinos de redirección también deben estar permitidos. No envía cookies ni cabeceras de autenticación, no reintenta nada automáticamente e informa de verified / digest-mismatch / unavailable / offline / unverified junto con la hora de observación. Las etiquetas o hashes cambiados necesitan una nueva revisión. HTTP de loopback solo está disponible mediante una opción explícita de fixture.

Los adaptadores pueden publicar un upstream-manifest revisado con inventario de API, revisión exacta del código fuente, licencia/NOTICE completos y hashes de archivos. inspectUpstreamManifest vincula esos metadatos a los bytes descargados; no analiza código fuente arbitrario ni infiere permiso de redistribución. createUpstreamCandidate devuelve diferencias de API/archivos/licencias y un parche con el resumen previo y el código fuente de sustitución. Coincidir con una matriz exacta de versiones sin una comprobación funcional del desarrollador sigue sin verificarse; una API obligatoria ausente se considera no compatible.

Un candidato compatible sigue necesitando revisión humana. Su matriz automaticActions está vacía; estas API no crean ramas, fusionan, publican, aprueban permisos nuevos ni instalan un monitor. El host controla la ejecución y cancelación de pruebas del adaptador. El ejemplo público completo siguiente solo ejercita fixtures locales. Las API de flujos de trabajo/caché/herramientas/LSP están disponibles en las secciones 1.2 siguientes.

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

Tipos, API, límites y código fuente ejecutable completo

Flujos de comandos y recuperación explícita

SDK 1.2 añade siete exportaciones opcionales: /workflows, /workflows-node, /workflow-cache, /workflow-cache-node, /tool-streams, /tool-streams-node y /lsp-node. El paquete actual tiene 50 exportaciones, 107 esquemas, declaraciones TypeScript y ejemplos independientes instalados, sin dependencias npm de ejecución. Solo /tool-streams es portable al navegador; las demás exportaciones nuevas requieren Node. El protocolo de espacio de trabajo existente y las API 1.x siguen siendo compatibles. Un plugin que importe una API nueva de 1.2 debe declarar 1.2.0 como versión mínima del SDK.

prepareWorkflowPlan valida identificadores de comandos registrados, pasos únicos, dependencias acíclicas, esquemas cerrados de datos de entrada/salida y vínculos obligatorios de salida antes de ejecutar. Cada entrada es un literal {value} o un vínculo {step, path} a una dependencia explícita. Las restricciones del esquema deben coincidir exactamente. El plan inmutable vincula sus comandos, permisos, ámbito y entradas a un SHA-256. run requiere approved: true y ese resumen revisado exacto. Los puertos authorize y execute del host siguen perteneciendo al operador.

createCommandJobExecutor conecta un PluginHost existente y aislado seleccionado por resolveHost, que devuelve el ámbito exacto del host, los permisos del paso y el hash del plugin. Los permisos nunca se combinan entre pasos. La autorización actual se comprueba antes de ejecutar, después de los resultados y antes de reutilizarlos. continue completa las ramas independientes y bloquea los descendientes fallidos; fail-fast cancela los pasos restantes. Los registros conservan identificadores del trabajo/intento padre, trabajos individuales, resúmenes de entrada/salida, artefactos, motivos y marcas de tiempo. Los aciertos de caché no tienen un nuevo identificador de trabajo y no pueden atribuirse artefactos mutables de trabajos.

recover lee un punto de control almacenado e informa del trabajo pendiente/en curso como interrumpido sin ejecutarlo. Una reanudación manual aporta el registro anterior exacto y previousAttemptId en una nueva aprobación, crea un nuevo intento y conserva solo resultados exitosos coincidentes y sin caducar. retrySteps vuelve a ejecutar los pasos seleccionados y sus descendientes incluso en un DAG desordenado. Una salida caducada requiere seleccionar explícitamente el reintento; cambiar esquema, entrada, permisos o hash del plugin requiere un nuevo plan. Un ejecutor que ignore la cancelación sigue contabilizado como no finalizado e impide reintentos superpuestos.

createNodeWorkflowStore utiliza directorios reales separados de almacén/espacio de trabajo, marcadores de identidad del ámbito y del sistema de archivos, un escritor, sobres con checksum y puntos de control CAS. Tras un fallo conocido, recoverStaleLock explícito solo acepta un propietario de la misma máquina cuya terminación esté probada. La limpieza predeterminada trata registros corruptos reconocidos y escrituras incompletas, conservando archivos/enlaces desconocidos. cleanup({expiredBefore}) también puede eliminar registros finales caducados; los registros activos permanecen para su recuperación. Windows no afirma disponer de fsync de directorio ni durabilidad ante pérdida de alimentación. Límites: 64 pasos, 8 pasos concurrentes, plazo de flujo de 10 minutos, 64 KiB por resultado, 1 MiB de salidas combinadas, registros de 2 MiB, 64 registros retenidos y como máximo 24 horas de retención de resultados parciales.

Tipos, API, límites y ejemplos ejecutables completos

Caché determinista y ejecución incremental

fingerprintWorkflowInputs calcula hashes de los bytes reales de archivos junto con versión del SDK, ámbito de espacio de trabajo/seguridad, esquema/entrada del comando, hashes de plugin/herramienta, ajustes, entorno declarado y permisos. mtime y la ruta por sí solos nunca identifican el contenido. El operador declara explícitamente optIn, deterministic, declaredInputsComplete y secretDependent. Las entradas desconocidas o incompletas, el no determinismo, la dependencia de secretos, el entorno ausente/no declarado y las entradas de referencia a secretos omiten la caché indicando el motivo. El host también debe excluir secretos en bruto y efectos secundarios; el SDK no puede inferir entradas ocultas.

createWorkflowCache vuelve a comprobar la autorización actual en lookup/fill/after-fill/hit/return y verifica hashes de valores, ámbito, permisos y caducidad. Los fallos de caché simultáneos y elegibles comparten un único cálculo; cancelar una espera no cancela las demás. Los valores caducados o dañados son fallos de caché. TTL/LRU, presupuestos de entradas/valores y limpieza del almacén propio controlan el almacenamiento; los fallos de escritura conservan los resultados calculados con un motivo explícito. Nunca se retienen resultados de referencias a secretos. Los límites de huella son 64 archivos, 4 MiB por archivo y 16 MiB en total; los de caché son 512 entradas, 16 MiB de bytes de valores retenidos, ocho cálculos y 60 segundos por cálculo.

El ejemplo de flujo consulta la caché solo después de que las dependencias actuales se completen correctamente. Un archivo cambiado invalida su paso; las salidas cambiadas invalidan las huellas de entradas dependientes. Una dependencia fallida bloquea al padre antes de buscar un resultado de padre en caché. Los comprobantes distinguen hit, miss, shared y bypass, ejecución real frente a reutilización, contadores de caché, bytes de almacenamiento y tiempos locales. El estado duradero de la caché usa directorios separados por propietario y sustitución atómica, con recuperación de escrituras huérfanas/corrupción; no elimina archivos fuente.

Tipos, API, límites y ejemplos ejecutables completos

Flujos de salida de herramientas registradas

createToolStreamParser es un decodificador portable y acotado de UTF-8 JSONL/texto. Espera write(bytes, stdout/stderr) para aplicar contrapresión y llama a finish solo después de terminar ambos flujos. Conserva caracteres multibyte divididos y líneas parciales finales, y emite eventos correlacionados de registro, progreso, diagnóstico y desconocidos. UTF-8 malformado y límites estrictos detienen el análisis. Se validan las rutas relativas de diagnóstico, las posiciones ordenadas y las severidades; el editor consumidor también debe validar las posiciones contra el texto actual del documento. createJobToolEventSink conecta progreso/registros a un JobReporter existente y deja los diagnósticos a un receptor propiedad del llamador.

El runner opcional de Node acepta registros fijos del operador: backend/herramienta/versión, ejecutable absoluto y versiones fijadas de implementaciones seleccionadas, sonda de versión exacta, entorno explícito, esquema de entrada cerrado y espacios obligatorios para argumentos escalares. Los espacios para archivos deben nombrar archivos relativos existentes en el espacio de trabajo. Una invocación del plugin selecciona solo una herramienta/versión ya registrada y entradas validadas; no puede elegir un shell ni un ejecutable. La autorización actual se comprueba antes de preparar/iniciar, en los eventos y después de finalizar. Los comprobantes conservan código de salida, motivo de cancelación/fallo y estadísticas de salida.

Los literales conocidos de secretos/rutas de una sola línea se enmascaran después de ensamblar las líneas, incluso si llegan en fragmentos divididos; los secretos codificados o desconocidos no se detectan automáticamente. El runner solo controla su hijo directo/tuberías y los cierra al cancelar o cerrar. No busca ni termina árboles de procesos ajenos o descendientes y no es un entorno aislado del sistema operativo. Límites: fragmentos de 64 KiB, líneas de 16 KiB, salida total de 2 MiB, 4.096 eventos, ocho escrituras en cola, receptores de cinco segundos, 32 herramientas y cuatro ejecuciones concurrentes. Una sonda separada de cinco segundos/16 KiB comprueba la versión configurada.

El fixture de herramienta redistribuible creado por el SDK prueba UTF-8/JSONL fragmentado, salida final, salidas distintas de cero, cancelación y límites. El adaptador real es TypeScript 5.9.3 con --noEmit --noLib --pretty false y un fixture desechable de tipos intrínsecos que produce TS2322. Proporciona explícitamente una raíz de TypeScript existente y aprobada para ejecutarlo. El SDK nunca instala ni descarga automáticamente una herramienta externa; los hashes aportados no autentican por sí mismos a su editor.

Tipos, API, límites y ejemplos ejecutables completos

Puente LSP público por stdio

createLspBridge conecta un proceso stdio fijado y aprobado explícitamente con solicitudes/proveedores de lenguaje existentes del SDK. Negocia el subconjunto admitido de LSP 3.17, posiciones UTF-16 e instantáneas completas. capabilities informa del soporte anunciado por separado de las ejecuciones exitosas. Los mapeos admitidos cubren autocompletado, información al pasar el cursor, definición, referencias, símbolos planos/jerárquicos, ayuda de firmas, prepare-rename/rename, formato de documento/rango, acciones de código, tokens semánticos completos, plegado e indicaciones en línea: 15 funciones del SDK.

syncDocument y closeDocument gestionan didOpen/didChange/didClose. Los cambios de versión y generación actuales cancelan trabajo obsoleto, se rechazan identificadores de solicitudes activas duplicados y se ignoran respuestas tardías. Las URI locales deben resolverse dentro del espacio de trabajo sin enlaces; el código fuente y los destinos de edición requieren autorización actual y una instantánea exacta abierta o proporcionada por el host. Los resultados de renombrado/formato/acciones son propuestas condicionales de edición del espacio de trabajo con hashes base, nunca ediciones aplicadas automáticamente ni comandos ejecutables.

Solo se aceptan diagnósticos con la versión actual del documento. Las notificaciones sin versión/obsoletas se descartan y contabilizan. Las funciones explícitamente no admitidas son resolución/snippets de autocompletado, resolución de acciones de código, deltas semánticos, comandos del servidor, capacidades dinámicas, operaciones de recursos, transportes de socket y diagnósticos sin versión. workspace/applyEdit devuelve applied:false. Límites: mensajes de 1 MiB, cabeceras de 8 KiB, sesiones de 64 MiB/20.000 mensajes, 16 solicitudes pendientes y escrituras en cola, 32 documentos/4 MiB de texto agregado, plazos de solicitudes de hasta 30 segundos y 64 KiB de stderr descartado.

close envía shutdown/exit y realiza una limpieza acotada del proceso directo/tuberías, distinguiendo confirmación normal, servidores que rechazan o fallan y cierre real del proceso. Un servidor puede confirmar shutdown y aun así necesitar que se detenga el proceso controlado. No hay reinicio ni reproducción automáticos: el operador crea un puente nuevo y reenvía explícitamente las instantáneas actuales seleccionadas. Las pruebas sintéticas cubren marcos malformados, fallos/tiempos de espera, cancelación/respuestas tardías, carreras entre documentos, rechazo del cierre, solicitudes no admitidas y todas las funciones mapeadas.

La comprobación real con un servidor independiente usa typescript-language-server 5.3.0 de la comunidad con TypeScript 5.9.3: se aprobaron autocompletado, información al pasar el cursor, definición, referencias, símbolos, ayuda de firmas, formato y tokens semánticos. Se fijan los archivos de implementación seleccionados y Node, la ruta de tsserver es fija y la adquisición automática de tipos está desactivada. Esta versión del servidor omite initialize.serverInfo opcional y envía diagnósticos sin versión, por lo que este puente declara explícitamente que no admite sus diagnósticos; los diagnósticos versionados se verifican con el servidor sintético independiente. El operador debe confiar en toda la herramienta instalada y en su acceso al sistema operativo.

La aceptación 1.2 incluye consumidores independientes del paquete, declaraciones, 107 esquemas, adaptadores reales de compilador/servidor e interoperabilidad con archivos públicos históricos. El ejemplo de flujo distingue recuperación duradera y reintento explícito de reproducción automática. La auditoría de seguridad y la validación de vulnerabilidades siguen pendientes por el aplazamiento del responsable. Esta versión no constituye aceptación de la UI de DDS, Engine, planificador de Cloud, Marketplace, instalador ni aislamiento de seguridad.

Tipos, API, límites y ejemplos ejecutables completos

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

Para adaptadores reales, añade rutas absolutas a instalaciones existentes aprobadas por el operador. Los ejemplos predeterminados usan solo fixtures creados por el SDK y nunca descargan una herramienta.

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