Desenvolvimento e versões do Plugin SDK

Ferramentas de desenvolvimento, verificação e lançamento, fluxos da versão 1.2, cache incremental, ferramentas externas e ponte LSP pública.

Orientações de desenvolvimento, verificação e lançamento para o DDS Plugin SDK 1.2.0. A auditoria de segurança e a validação de vulnerabilidades estão pendentes; o estado estável da API e as verificações funcionais não constituem aceitação de segurança.

Guia de instalação e API do SDK

Modelos de desenvolvimento e geração

Escolha command, language, theme, job, browser ou configuration. init --dry-run informa o destino, o inventário de arquivos, os hashes e os conflitos sem gravar nem instalar. O init normal exige um novo diretório real. Cada modelo inclui arquivos-fonte, manifesto, declaração de informações, licença/avisos, testes, um consumidor tipado e um exemplo executável. Os modelos browser e configuration incluem uma demonstração de loopback. As dependências geradas fixam o arquivo exato do 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 contém dados JSON com limites definidos para esquemas de comandos, configurações, catálogos de idiomas e dados de temas. generate emite JSON de execução, exports ESM, tipos TypeScript de entrada bruta/validada, tipos de saída/configurações, JSON Schema e XML de tema. Os valores padrão de JSON Schema são anotações; apenas a validação de entrada do SDK aplica os padrões. A geração não importa seu plugin. doctor verifica divergências, metadados, módulos ausentes e se os arquivos gerados de execução estão incluídos na lista de permissões do pacote.

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>

A substituição exige o hash anterior exato e bytes gerados inalterados. Edições manuais, arquivos extras, links e locks antigos interrompem a substituição. As falhas removem apenas as entradas inalteradas pertencentes àquela tentativa e preservam entradas modificadas ou incertas para inspeção. Os arquivos são limitados a 256, com 1 MiB por arquivo e 4 MiB no total. O lock coordena geradores cooperativos; não é proteção contra um escritor concorrente hostil no sistema de arquivos nem uma transação atômica entre diretórios. Modelos proprietários exigem termos fornecidos pelo chamador e preservam os arquivos de licença/avisos herdados do SDK.

Testes determinísticos e reprodução

createScenarioHost de /testing monta explicitamente as fixtures selecionadas em memória de arquivos, backend, configurações, segredos e jobs. Ele começa sem autorizações nem recursos. createTestClock fornece IDs com semente, tempo e temporizadores sem modificar variáveis globais; temporizadores com o mesmo horário mantêm a ordem de inserção. Aguarde o avanço do relógio para desbloquear esperas virtuais. Os UUIDs gerados são dados de teste, não entropia criptográfica. Os padrões existentes de createTestHost permanecem compatíveis.

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

As portas de falhas modelam atrasos, recusas, desconexões, corrupção, esgotamento e chamadas descartadas; fixtures de eventos podem ser descartadas, duplicadas ou invertidas sem repetir efeitos externos. replaceGrants desativa plugins que perdem autoridade. Snapshots de jobs em memória validam identidade, revisão e hashes e modelam recuperação após interrupção sem execução automática. Essas fixtures não emulam a durabilidade do sistema de arquivos nem descobrem identificadores do sistema operacional. Um registro separado do proprietário acompanha os recursos registrados explicitamente. A desmontagem preserva as contagens pendentes de callbacks que ignoram o cancelamento até que eles realmente se encerrem. A inspeção de configurações agora pode ser lida após o descarte; leituras de dados ainda são rejeitadas.

A gravação exige synthetic: true e um inventário explícito de fixtures com limites definidos. Os rastros exportados contêm apenas tipos de operação, IDs de fixtures, tempos, semente/versão e hashes encadeados. Use IDs sem dados sensíveis; hashes não anonimizam dados que podem ser adivinhados, e o SDK não consegue classificar uma entrada arbitrária como sintética. A reprodução pura verifica ordem, hashes e identidade das fixtures e retorna saídas selecionadas das fixtures; ela não aceita callback de efeito. Os limites incluem 64 fixtures, 1.024 eventos e um rastro de 1 MiB. Execute o exemplo empacotado de ferramentas de desenvolvimento para verificações de falhas, recuperação, privacidade e limpeza.

Diagnósticos locais e depuração

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

Os diagnósticos estão desativados por padrão e são apenas locais. Os relatórios contêm códigos fixos de operação/status/erro, IDs de correlação, durações e contagens de recursos; não há API para corpos de documentos, caminhos, entradas, corpos de saída ou texto arbitrário de exceções. As contagens de bytes, profundidade das filas e valores de memória são estimativas explícitas do proprietário. profileTransport mede até a chamada encapsulada se resolver, o que, para fetch, corresponde aos cabeçalhos da resposta, não à conclusão do corpo. Os registros concluídos usam um buffer circular limitado e expiração passiva; não há temporizadores de diagnóstico em segundo plano nem envio de dados. Os padrões são 128 eventos/60 segundos; os máximos são 256 eventos/5 minutos, 64 spans em andamento e 256 KiB por relatório.

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

O modo de depuração expõe apenas um inspetor temporário em 127.0.0.1 no processo filho controlado. --debug-wait pausa antes de importar o plugin e exige --debug. O orçamento total da execução inclui a espera pelo depurador e é de no máximo 30 segundos. Conclusão, cancelamento e timeout encerram o processo filho controlado e o inspetor. Tanto o profiling quanto a depuração exigem confiança explícita no código local; nenhum deles é um sandbox. Falhas ou encerramento forçado podem omitir o relatório de profiling, e stdout/stderr brutos do plugin permanecem um fluxo separado e limitado, sem remoção automática de dados sensíveis.

Ferramentas de desenvolvimento · Testes · Diagnósticos · Compatibilidade

Conformidade do host

O módulo /conformance executa verificações sintéticas versionadas no host e nos adaptadores de configurações, espaço de trabalho, localização, testes, diagnósticos e desenvolvimento fornecidos explicitamente por você. Ele distingue perfis compatíveis, incompatíveis e com falha e inclui host/versão/ambiente de execução/plataforma, ID da verificação, tempos e limpeza. Um recurso declarado com um adaptador ausente ou defeituoso falha; recursos opcionais desconhecidos são registrados sem teste. Comandos, permissões e cancelamento são exigidos por padrão.

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

Substitua a fábrica de hosts pelo seu adaptador e execute também os testes do seu plugin. O auxiliar Node /conformance-node cria apenas fixtures temporárias novas e servidores temporários de loopback. O exemplo de navegador executa os perfis de navegador disponíveis e informa os recursos Node ausentes como incompatíveis. As verificações rápidas amostram contratos; exemplos vinculados e testes de lançamento cobrem caminhos maiores de linguagem, recuperação e armazenamento. Um relatório é evidência de teste, não um certificado de confiança.

Os prazos são de 10 segundos por caso por padrão, até o máximo de 30 segundos. Timeout ou cancelamento interrompe os casos seguintes; falha na limpeza reprova o caso, e limpeza pendente permanece sem verificação. Adaptadores confiáveis no mesmo processo podem bloquear de forma síncrona e manter a autoridade do ambiente. Os relatórios excluem corpos de erro de provedores, payloads, tokens e caminhos; escolha rótulos de identidade sem dados sensíveis. Nenhum relatório é enviado automaticamente.

Suporte e migração do SDK

API_SUPPORT.json lista todos os módulos exportados, nomes em execução, declarações, hashes das declarações, ambientes e estabilidade. APIs estáveis 1.x seguem versionamento semântico: adições compatíveis usam uma versão minor e alterações incompatíveis em APIs estáveis exigem uma nova major. artifact-resume-browser permanece experimental e precisa de uma versão exata do SDK/navegador com uma nova aceitação no navegador. A descoberta de recursos opcionais e as permissões atuais continuam necessárias.

A política da linha estável se aplica desde a 1.0.0. A minor estável mais recente recebe correções comuns; a minor anterior continua elegível para correções críticas de segurança durante 90 dias dentro de um ambiente de execução com suporte. Nenhuma API estável está obsoleta na 1.0.0. As descontinuações são anunciadas por pelo menos duas versões minor e seis meses antes da remoção em uma major. RCs e prévias são substituídos. Esta política de código aberto não promete tempos de resposta comerciais.

A aceitação de servidor e CLI cobre Windows/Linux com Node 22 ou 24 corrigido e declarações com TypeScript 5.9.3. O suporte ao Node 22 termina em 2027-04-30 e ao Node 24 em 2028-04-30. Os comprovantes de lançamento identificam as versões exatas de patch, imagens de sistema operacional e build do navegador. Outros ambientes de execução e combinações de navegador/armazenamento precisam de sua própria aceitação. As dependências npm de execução do SDK continuam vazias.

Plugins estáveis 1.0 usam >=1.0.0 <2.0.0; aumente a versão mínima ao adotar uma API posterior. Pacotes RC1 mantêm seu peer exato 1.0.0-rc.1. Revalide e publique uma nova versão do plugin para alterá-lo; mantenha os arquivos anteriores imutáveis. Arquivos legados são entradas de interoperabilidade, não linhas mantidas. Após reiniciar, estabeleça uma nova conexão e as autorizações atuais; a recuperação lê o estado confirmado sem executar o trabalho novamente.

Aceitação do lançamento

A auditoria de segurança e a validação de vulnerabilidades estão pendentes conforme o adiamento do proprietário em 2026-10-05. Resultados funcionais, de compatibilidade e de desempenho não constituem aceitação de segurança. A revisão preservada será retomada separadamente; esta versão não deve ser descrita como aprovada nessa auditoria.

A fixture combinada exercita simultaneamente linguagem/configurações, edições revisadas, jobs de comandos, observação de projetos, envio/download e armazenamento preservado. Ela verifica interrupções, respostas malformadas, revogação, mudanças de geração, recuperação e limpeza de recursos. Testes separados de sistema de arquivos/processos cobrem processos filhos encerrados, corrupção, gravações com falha, expiração e cancelamento ignorado. O relatório de aceitação RC vincula comandos reproduzíveis e os limites de cada resultado.

O desempenho registra cinco amostras em processos novos para cada perfil Windows/Linux e Node 22/24, incluindo mediana/dispersão, tempo de CPU, memória amostrada, tempos de importação/inicialização/observação e contagens lógicas de payloads de disco/HTTP. Os limiares de referência vêm dessas amostras medidas e são proteções aproximadas contra regressões, não um SLA de latência. Eles não medem tráfego físico de disco nem garantem a descoberta de todos os identificadores do sistema operacional.

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

Conformidade · Inventário de APIs · Política de suporte · Aceitação RC

Conteúdo da versão estável 1.0

O pacote original 1.0 inclui 38 exports e 86 esquemas com declarações, exemplos, LICENSE e NOTICE. A 1.1 adiciona as ferramentas de lançamento abaixo; a 1.2 adiciona as seções de fluxos/cache/ferramentas/LSP abaixo. Os comprovantes de lançamento distinguem arquivos-fonte/CI/hashes exatos, novos consumidores e evidências reutilizadas de navegador.

Para voltar a uma versão anterior, interrompa o trabalho controlado e selecione explicitamente arquivos compatíveis preservados do SDK/plugin e uma exportação de configuração. Revise as autorizações atuais e crie uma nova conexão. A recuperação de resultados é apenas por leitura; efeitos externos e configurações incompatíveis não são desfeitos automaticamente. Teste os formatos e recursos opcionais realmente usados.

Conteúdo da versão, migração e suporte

Pacotes offline e SBOM

O SDK 1.1 adiciona cinco pontos de entrada opcionais exclusivos de Node: /bundles, /provenance, /updates, /updates-node e /upstream. O pacote contém 43 exports, 96 esquemas, declarações e exemplos executáveis, sem dependências npm de execução. As APIs 1.0 existentes e os arquivos .tgz não assinados do DDS permanecem compatíveis.

lockBundleDependency fixa uma árvore revisada de arquivos ESM/CommonJS a uma versão exata, origem HTTPS, hash canônico dos arquivos, mapa de dependências, LICENSE/NOTICE e decisão explícita de redistribuição. O hash descreve a árvore revisada; não é um hash do arquivo upstream. createPluginBundle incorpora o arquivo original do plugin DDS e os metadados da versão, um grafo acíclico de dependências com uma versão por pacote e um SBOM CycloneDX 1.6 determinístico.

verifyPluginBundle verifica o snapshot exato e limitado de bytes. installPluginBundle exige seu expectedSha256, approved: true e um novo diretório sob um diretório pai controlado pelo operador. Ele não executa npm, scripts de ciclo de vida, downloads ou código de plugins. As dependências não herdam novas autorizações. O SDK do host é uma dependência separada. Addons nativos, mapas de exports e resolução arbitrária de dependências npm estão fora desse formato.

Limites: 32 pacotes de dependências, 1.024 arquivos expandidos, 4 MiB por arquivo de dependência, 32 MiB de conteúdo expandido e 48 MiB no pacote codificado. O arquivo original raiz tem seus próprios limites menores. Versões ausentes ou conflitantes, ciclos, dependências órfãs, hashes alterados, licenças/NOTICE ausentes, caminhos/links e colisões entre arquivos e diretórios são rejeitados. Instalações com falha preservam o novo destino para inspeção. Exclua escritores concorrentes; esta ferramenta não é um sandbox do sistema operacional.

Assinaturas separadas e confiança do operador

createProvenanceStatement vincula o nome/versão/SHA-256 exatos do pacote, editor, revisão dos arquivos-fonte e horários de emissão/expiração. signPluginProvenance usa um KeyObject Ed25519 controlado pelo chamador. canonicalProvenancePayload expõe DDS-PROVENANCE-V1 seguido por JSON canônico para que outro signatário reproduza o mesmo payload. O SDK não fornece chave privada de assinatura nem autoridade de assinatura de produtos DDS.

verifyPluginProvenance recebe raízes de confiança selecionadas pelo operador, vínculos de editor/objeto, horário atual, validade/revogação da chave e evidências de revogação com marca temporal. A verificação offline usa as evidências fornecidas e aplica o mesmo limite de atualidade; ela nunca busca sozinha informações novas de revogação. Uma nova chave de pacote não é confiável até que o operador a adicione. Raízes explícitas com sobreposição permitem rotação. A diferença máxima de relógio é de cinco minutos e a idade máxima das evidências é de 30 dias; selecione limites mais rigorosos quando necessário.

Os comprovantes mantêm soma de verificação, assinatura, editor e política separados e sempre retornam executionAuthorized: false. Uma assinatura não comprova a segurança do código nem concede execução, acesso a dados ou autoridade de sandbox. Pacotes anteriores não assinados exigem envelope: null e allowUnsigned: true, ainda informando ausência de assinatura e editor não verificado. A auditoria de segurança e a validação de vulnerabilidades continuam pendentes independentemente.

Revisar, ativar e reverter

createPluginUpdatePlan compara versão antiga/nova, API, autorizações, origens/hashes de dependências, ferramentas declaradas, licenças, hashes de configurações, identidade da migração, assinatura e chave e depois fixa o hash da revisão. createPluginUpdateController controla o host autorizado e as configurações atuais, além das portas getPolicy/prepare do operador. Stage verifica e cria um snapshot da candidata; approve deve corresponder ao hash exato do plano, às autorizações e ao ID da chave. Activate verifica as configurações atuais e atualiza a confiança antes e depois de preparar um host candidato separado.

wait adia a ativação enquanto há jobs em execução. retain-old deixa os jobs antigos no host/configurações/hash originais e envia novas execuções ao novo host após a troca. execute retorna o hash do plugin junto com cada resultado. Os jobs não são cancelados implicitamente. A substituição de configurações invalida uma aprovação pendente; alterações concorrentes e falhas de preparação preservam ou informam explicitamente o estado anterior. Rollback prepara o pacote/configurações antigo como uma nova atualização revisada e exige confiança atual e nova aprovação.

Preparação e migrações são executadas por portas confiáveis controladas pelo operador. Nem a reversão nem uma falha desfaz arquivos externos, requisições de rede ou outros efeitos. reversible é um metadado de revisão, não uma promessa de desfazer automático. Um journal Node é somente de acréscimo, tem um único escritor e fica fora do espaço de trabalho, com CAS de revisão exata e limites de 256 registros / 128 KiB por envelope / 8 MiB no total. Arquive sob controle do operador antes de abrir um journal novo ao atingir o limite.

inspectNodeUpdateJournal lê o estado persistido sem reprodução. Uma falha durante preparing ou uma confirmação ambígua exige leitura explícita do host/configurações; reconcilePluginUpdateJournal registra um hash antigo/novo conhecido e aprovado e um hash de configurações. Trechos finais corrompidos precisam de inspeção/reparo do operador. recoverStaleLock recupera apenas um escritor da mesma máquina comprovadamente encerrado. Isso não promete uma transação entre processos de host/configurações nem atomicidade universal em caso de perda de energia.

Verificações upstream e candidatas explícitas

fetchUpstreamArtifact precisa de uma chamada explícita, enabled: true, URL/versão/hash exatos da origem, lista de permissões exata de URLs, política offline, orçamento de bytes e prazo. Os destinos de redirecionamento também devem estar na lista de permissões. Ele não envia cookies nem cabeçalhos de autenticação, não repete nada automaticamente e informa verified / digest-mismatch / unavailable / offline / unverified com o horário da observação. Tags ou hashes alterados precisam de nova revisão. HTTP de loopback está disponível apenas por uma opção explícita de fixture.

Adaptadores podem publicar um upstream-manifest revisado contendo inventário de APIs, revisão exata dos arquivos-fonte, licença/NOTICE completos e hashes dos arquivos. inspectUpstreamManifest vincula esses metadados aos bytes baixados; não analisa código-fonte arbitrário nem infere permissão de redistribuição. createUpstreamCandidate retorna diferenças de API/arquivos/licença e um patch com hash anterior/origem de substituição. Corresponder a uma matriz exata de versões sem uma verificação funcional do desenvolvedor permanece sem verificação; uma API obrigatória ausente é incompatível.

Uma candidata compatível ainda exige revisão humana. Seu array automaticActions está vazio; essas APIs não criam uma branch, fazem merge, publicam, aprovam novas autorizações nem instalam um monitor. O host controla a execução e o cancelamento dos testes de adaptadores. O exemplo público completo abaixo exercita apenas fixtures locais. As APIs de fluxos/cache/ferramentas/LSP estão disponíveis nas seções da 1.2 abaixo.

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

Tipos, API, limites e código-fonte executável completo

Fluxos de comandos e recuperação explícita

O SDK 1.2 adiciona sete exports opcionais: /workflows, /workflows-node, /workflow-cache, /workflow-cache-node, /tool-streams, /tool-streams-node e /lsp-node. O pacote atual tem 50 exports, 107 esquemas, declarações TypeScript e exemplos instalados independentes, sem dependências npm de execução. Apenas /tool-streams é portável para o navegador; os outros novos exports exigem Node. O protocolo existente do espaço de trabalho e as APIs 1.x permanecem compatíveis. Um plugin que importe uma nova API 1.2 deve declarar 1.2.0 como sua versão mínima do SDK.

prepareWorkflowPlan valida IDs registrados de comandos, etapas únicas, dependências acíclicas, esquemas fechados de dados de entrada/saída e vínculos obrigatórios de saída antes da execução. Cada entrada é um literal {value} ou um vínculo {step, path} para uma dependência explícita. As restrições de esquema devem corresponder exatamente. O plano imutável vincula seus comandos, autorizações, escopo e entradas a um SHA-256. run exige approved: true e esse hash exato revisado. As portas authorize e execute do host continuam controladas pelo operador.

createCommandJobExecutor conecta um PluginHost existente e isolado selecionado por resolveHost, que retorna o escopo exato do host, as autorizações da etapa e o hash do plugin. As autorizações nunca são combinadas entre etapas. A autorização atual é verificada antes da execução, após os resultados e antes da reutilização. continue conclui ramificações independentes e bloqueia descendentes com falha; fail-fast cancela as etapas restantes. Os registros preservam IDs de job pai/tentativa, jobs individuais, hashes de entrada/saída, artefatos, motivos e horários. Resultados de cache não têm um novo ID de job nem podem reivindicar artefatos mutáveis de jobs.

recover lê um checkpoint armazenado e informa trabalho pendente/em execução como interrompido sem executá-lo. Uma retomada manual fornece o registro anterior exato e previousAttemptId em uma nova aprovação, cria uma nova tentativa e preserva apenas os resultados bem-sucedidos correspondentes e não expirados. retrySteps executa novamente as etapas selecionadas e seus descendentes mesmo em um DAG sem ordenação. Uma saída expirada exige seleção explícita de repetição; alterações de esquema, entrada, autorizações ou hash do plugin exigem um novo plano. Um executor que ignore cancelamento continua contado como não encerrado e impede repetições sobrepostas.

createNodeWorkflowStore usa diretórios reais e separados de armazenamento/espaço de trabalho, marcadores de escopo e identidade do sistema de arquivos, um escritor, envelopes com soma de verificação e checkpoints CAS. Após uma falha conhecida, recoverStaleLock explícito só aceita um proprietário da mesma máquina comprovadamente encerrado. A limpeza padrão trata registros reconhecidos como corrompidos e gravações inacabadas, preservando arquivos/links desconhecidos. cleanup({expiredBefore}) também pode remover registros finais expirados; registros ativos permanecem para recuperação. No Windows, não se reivindica fsync de diretório nem durabilidade diante de perda de energia. Limites: 64 etapas, 8 etapas simultâneas, prazo de 10 minutos para o fluxo, 64 KiB por resultado, 1 MiB de saídas combinadas, registros de 2 MiB, 64 registros preservados e no máximo 24 horas de retenção de resultados parciais.

Tipos, API, limites e exemplos executáveis completos

Cache determinístico e execução incremental

fingerprintWorkflowInputs calcula hashes dos bytes reais dos arquivos mais versão do SDK, escopo do espaço de trabalho/segurança, esquema/entrada do comando, hashes de plugin/ferramenta, configurações, ambiente declarado e autorizações. mtime e caminho, por si só, nunca são identidades de conteúdo. O operador declara explicitamente optIn, deterministic, declaredInputsComplete e secretDependent. Entradas desconhecidas ou incompletas, não determinismo, dependência de segredos, ambiente ausente/não declarado e entradas com referências a segredos ignoram o cache com um motivo. O host também deve excluir segredos brutos e efeitos colaterais; o SDK não consegue inferir entradas ocultas.

createWorkflowCache verifica novamente a autorização atual em lookup/fill/after-fill/hit/return e verifica hashes dos valores, escopo, autorizações e expiração. Ausências simultâneas elegíveis compartilham um único preenchimento; cancelar um participante em espera não cancela os demais. Valores expirados ou danificados são tratados como ausentes. TTL/LRU, orçamentos de entradas/valores e limpeza do armazenamento controlado governam o armazenamento; falhas de gravação continuam como resultados calculados com um motivo explícito. Resultados com referências a segredos nunca são preservados. Os limites de fingerprint são 64 arquivos, 4 MiB cada e 16 MiB no total; os limites do cache são 512 entradas, 16 MiB de bytes de valores preservados, oito preenchimentos e 60 segundos por preenchimento.

O exemplo de fluxo consulta o cache somente depois que as dependências atuais são concluídas com sucesso. Um arquivo alterado invalida sua etapa; saídas alteradas invalidam fingerprints de entradas dependentes. Uma dependência com falha bloqueia a etapa pai antes de consultar um resultado pai em cache. Os comprovantes distinguem hit, miss, shared e bypass, execução real de reutilização, contadores de cache, bytes armazenados e tempos locais. O estado persistente do cache usa diretórios separados do proprietário e substituição atômica, com recuperação de gravações órfãs/corrupção; ele não exclui arquivos-fonte.

Tipos, API, limites e exemplos executáveis completos

Fluxos de saída de ferramentas registradas

createToolStreamParser é um decodificador UTF-8 JSONL/texto portável e com limites definidos. Aguarde write(bytes, stdout/stderr) para respeitar a contrapressão e finalize apenas depois que ambos os fluxos terminarem. Ele preserva caracteres multibyte divididos e linhas finais parciais, emitindo eventos correlacionados de log, progresso, diagnóstico e desconhecidos. UTF-8 malformado e limites rígidos interrompem a análise. Caminhos relativos de diagnóstico, posições ordenadas e níveis de gravidade são validados; o editor consumidor também deve validar as posições em relação ao texto atual do documento. createJobToolEventSink conecta progresso/logs a um JobReporter existente e deixa os diagnósticos para um destino controlado pelo chamador.

O runner Node opcional aceita registros fixos do operador: backend/ferramenta/versão, executável absoluto e partes selecionadas da implementação fixadas, verificação exata de versão, ambiente explícito, esquema fechado de entrada e posições obrigatórias de argumentos escalares. As posições de arquivos devem nomear arquivos relativos existentes no espaço de trabalho. Uma chamada de plugin seleciona apenas uma ferramenta/versão já registrada e uma entrada validada; ela não pode escolher um shell nem um executável. A autorização atual é verificada antes da preparação/início, nos eventos e após a conclusão. Os comprovantes preservam código de saída, motivo de cancelamento/falha e estatísticas da saída.

Literais conhecidos de segredos/caminhos de uma linha são mascarados após a montagem da linha, incluindo partes divididas; segredos codificados ou desconhecidos não são detectados automaticamente. O runner controla apenas seu filho direto e os pipes e os fecha ao cancelar ou fechar. Ele não procura nem encerra árvores de processos sem relação ou descendentes e não é um sandbox do sistema operacional. Limites: partes de 64 KiB, linhas de 16 KiB, saída total de 2 MiB, 4.096 eventos, oito gravações enfileiradas, destinos de cinco segundos, 32 ferramentas e quatro execuções simultâneas. Uma verificação separada de cinco segundos/16 KiB confere a versão configurada.

A fixture de ferramenta redistribuível criada pelo SDK testa UTF-8/JSONL fragmentado, saída final, saídas diferentes de zero, cancelamento e limites. O adaptador real é TypeScript 5.9.3 com --noEmit --noLib --pretty false e uma fixture descartável de tipos intrínsecos que produz TS2322. Forneça explicitamente uma raiz TypeScript aprovada e existente para executá-lo. O SDK nunca instala nem baixa automaticamente uma ferramenta externa; hashes fornecidos não autenticam de forma independente seu editor.

Tipos, API, limites e exemplos executáveis completos

Ponte LSP stdio pública

createLspBridge conecta um processo stdio fixado e aprovado explicitamente a requisições/provedores de linguagem existentes do SDK. Ele negocia o subconjunto compatível de LSP 3.17, posições UTF-16 e snapshots completos. capabilities informa o suporte anunciado separadamente das execuções bem-sucedidas. Os mapeamentos compatíveis abrangem completion, hover, definition, references, símbolos planos/hierárquicos, ajuda de assinatura, prepare-rename/rename, formatação de documento/intervalo, ações de código, tokens semânticos completos, dobramento e inlay hints: 15 recursos do SDK.

syncDocument e closeDocument tratam didOpen/didChange/didClose. Alterações da versão e geração atuais cancelam trabalho desatualizado, IDs duplicados de requisições ativas são rejeitados e respostas tardias são ignoradas. URIs locais devem resolver dentro do espaço de trabalho sem links; arquivos-fonte e destinos de edição exigem autorização atual e um snapshot exato aberto ou fornecido pelo host. Resultados de rename/format/action são propostas condicionais de edição do espaço de trabalho com hashes de base, nunca edições aplicadas automaticamente nem comandos executáveis.

Diagnósticos são aceitos apenas com a versão atual do documento. Notificações sem versão/desatualizadas são descartadas e contadas. Recursos explicitamente incompatíveis são resolução de completion/snippets, resolução de ações de código, deltas semânticos, comandos do servidor, recursos dinâmicos, operações de recursos, transportes de socket e diagnósticos sem versão. workspace/applyEdit retorna applied:false. Limites: mensagens de 1 MiB, cabeçalhos de 8 KiB, sessões de 64 MiB/20.000 mensagens, 16 requisições pendentes e gravações enfileiradas, 32 documentos/4 MiB de texto agregado, prazos de requisição de até 30 segundos e 64 KiB de stderr descartado.

close envia shutdown/exit e executa limpeza limitada do processo direto/pipes, distinguindo confirmação normal, servidores que recusam ou falham e encerramento real do processo. Um servidor pode confirmar shutdown e ainda precisar que o processo controlado seja parado. Não há reinício nem reprodução automática: o operador cria uma nova ponte e reenvia explicitamente os snapshots atuais selecionados. Testes sintéticos cobrem enquadramento malformado, falha/timeout, cancelamento/respostas tardias, condições de corrida de documentos, recusa de shutdown, requisições incompatíveis e todos os recursos mapeados.

A verificação real de servidor independente usa o typescript-language-server 5.3.0 da comunidade com TypeScript 5.9.3: completion, hover, definition, references, símbolos, ajuda de assinatura, formatação e tokens semânticos passaram. Arquivos selecionados da implementação e Node são fixados, o caminho do tsserver é fixo e a aquisição automática de tipos é desativada. Essa versão do servidor omite initialize.serverInfo opcional e envia diagnósticos sem versão; portanto, seus diagnósticos são explicitamente incompatíveis com esta ponte; diagnósticos versionados são verificados usando o servidor sintético independente. O operador deve confiar em toda a ferramenta instalada e em seu acesso ao sistema operacional.

A aceitação da 1.2 inclui consumidores empacotados independentes, declarações, 107 esquemas, os adaptadores reais de compilador/servidor e a interoperabilidade histórica com arquivos públicos. O exemplo de fluxo distingue recuperação persistente e repetição explícita de reprodução automática. A auditoria de segurança e a validação de vulnerabilidades continuam pendentes conforme o adiamento do proprietário. Esta versão não constitui aceitação de DDS UI, Engine, agendador do Cloud, Marketplace, instalador ou sandbox de segurança.

Tipos, API, limites e exemplos executáveis 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 reais, adicione caminhos absolutos para instalações existentes aprovadas pelo operador. Os exemplos padrão usam apenas fixtures criadas pelo SDK e nunca baixam uma ferramenta.

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