Desenvolvimento com o Titan Architect SDK

Baixe e confira o SDK

Baixe titan-architect-sdk.zip e o arquivo titan-architect-sdk.zip.sha256 da mesma versão. Na pasta dos arquivos, confira o checksum e extraia o SDK.

sha256sum -c titan-architect-sdk.zip.sha256
unzip titan-architect-sdk.zip

O pacote inclui bibliotecas PHP e TypeScript, contratos, exemplos, documentação e ferramentas para gerar e assinar plugins. O assinador verifica o FEX usando PHP com Zip e Sodium. Para gerar os dois arquivos a partir do repositório, execute python3 titanArchitect-sdk/tools/publicar-sdk.py /tmp/titan-sdk-public.

Escolha o tipo de extensão

Plugins nativos são mantidos junto ao Titan Continuum. O núcleo descobre os manifestos instalados em titansource/plugins/native/<módulo>. Essa pasta recebe código nativo revisado e publicado pelo mantenedor da instalação. Use Chamados como referência para rotas, menu, permissões e migrações. Use Downloads como referência para preservar um serviço consumido por clientes legados.

Extensões de terceiros usam as bibliotecas PHP ou TypeScript sem acessar a sessão ou as credenciais do Titan. O SDK pode ser exercitado localmente com um transporte injetado. O Plugin Manager recebe, verifica e registra pacotes externos assinados. Execução depende do runtime isolado e do canal autenticado descritos na arquitetura.

Gere a estrutura

Use python3 titanArchitect-sdk/tools/novo-plugin.py php empresa.modulo /tmp/empresa-modulo ou troque php por typescript. O gerador cria manifesto, entrada em src/, testes e dependências locais do SDK. O README do SDK mostra os comandos de build e assinatura.

Valide antes de empacotar

Rode os testes do seu plugin. Para TypeScript, execute npm run build no projeto para gerar a entrada JavaScript do manifesto. O validador usa PHP e Node.js para conferir a sintaxe dos arquivos executáveis selecionados.

php titanArchitect-sdk/tools/validar-plugin.php /tmp/plugin-php manifest.json src/plugin.php
php titanArchitect-sdk/tools/validar-plugin.php /tmp/plugin-ts manifest.json dist/plugin.js

Sem uma lista, o comando valida o manifesto e a entrada declarada. Inclua na lista todos os arquivos a entregar para conferir também nomes, caminhos e tamanho do conjunto. A saída indica ID, versão, runtime e quantidade de arquivos validados. O empacotador aplica a mesma validação antes de assinar.

Use o design e preserve contratos existentes

Adicione design/plugin.css à sua interface e mantenha as classes dentro de .titan-plugin. O CSS herda as variáveis --titan-ui-* do host e tem valores padrão para testes locais. Para abrir o painel de exemplo, rode php -S 127.0.0.1:8000 -t titanArchitect-sdk/design e acesse /painel.php.

O kit de compatibilidade traz um inventário de rotas que ajuda a preservar aliases, tópicos WebSocket, permissões e esquemas durante a migração.

Siga o tutorial de rotas e permissões WebSocket para registrar um canal no manifesto, proteger o controlador e atualizar a interface quando o núcleo entregar um aviso.

Registre um plugin nativo

  1. Crie o diretório em titansource/plugins/native e adicione um manifesto com id namespaced, versão, apiVersion: 1, runtime: "php" e o nome do arquivo de entrada. Para um diretório pendencias, use rotas ext-pendencias/index e permissões com prefixo plugin_pendencias.. Declare o controlador de cada rota em controllers. A instalação ocorre ao incluir a pasta revisada na distribuição; o núcleo continua igual.
  2. Declare dependencies com os IDs necessários e as permissões com rótulos nos grupos do catálogo. Declare menu e ícone em navigation, com as permissões em requires. O header consome as entradas de navegação e aplica as permissões declaradas. O catálogo da Administração recebe as permissões dos manifestos registrados. Nos controladores mantenha as verificações de sessão, escopo, permissão, CSRF e método.
  3. Ao migrar código existente, mantenha a URL antiga por uma fachada ou uma rota nativa registrada. Chamados usa controllers para mapear URLs a arquivos privados do plugin. Preserve funções públicas, argumentos, formatos de resposta, ordem de escrita e grupos de autorização. Mantenha uma implementação por operação.
  4. Declare as chaves e versões de esquemas em schemas. Mantenha as chaves usadas pela instalação anterior. Aplique as migrações pelo núcleo antes de iniciar a transação da operação de negócio.
  5. Declare serviceProvider com um arquivo PHP que retorna uma função de registro. Registre uma operação no gateway com capacidade explícita e use o serviço que possui a regra de negócio. O host vincula o ator autenticado e as concessões da instalação. Pedidos JSON não escolhem o ator nem suas permissões.
  6. Teste o caminho antigo, o novo contrato e o rollback usando um banco isolado. O registro de módulos nativos não oferece desinstalação ou desativação automática.

Recursos públicos

Coloque os recursos em assets/ no plugin. Informe a lista de caminhos no manifesto, por exemplo "assets":["painel.css","js/filtros.js"]. Para o plugin instalado na pasta pendencias, a folha de estilos fica em /plugin-assets/pendencias/painel.css. Gere a URL com reversaUrl('plugin-assets/pendencias/painel.css') se a aplicação puder ser montada abaixo de um prefixo. Declare somente arquivos públicos. Scripts PHP, manifestos, downloads privados e arquivos do banco ficam fora desse catálogo.

Migrações e tabelas

Um plugin nativo pode criar e alterar suas próprias tabelas e continuar usando as tabelas já existentes que possui. Para tabelas de outro módulo ou do núcleo, use o serviço responsável. Dependências SQL legadas devem ser inventariadas e preservadas durante a migração para serviços. As credenciais do núcleo não são distribuídas às extensões de terceiros.

use Titan\Architect\Core\NativeMigrations;

NativeMigrations::apply($pdo, 'empresa.exemplo', 'empresa_exemplo', static function () use ($pdo): void {
    $pdo->exec('CREATE TABLE IF NOT EXISTS empresa_exemplo_itens (
        id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
        referencia VARCHAR(80) NOT NULL
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4');
});

O exemplo exige um plugin nativo aprovado com "schemas": {"empresa_exemplo": 1} no manifesto. O núcleo serializa a migração e registra a versão somente após o callback. DDL MySQL pode efetuar commit implícito. Prepare alterações aditivas e idempotentes, com backup e restauração testados. Para terceiros, o armazenamento deve ser separado ou concedido com credenciais exclusivas e escopo limitado.

Use o SDK

PHP 8.2 ou superior. Carregue o SDK via Composer e passe ao cliente o canal JSON confiável cedido pelo host.

$client = new Forge\Client(Closure::fromCallable(new Forge\JsonTransport($exchange)));
$manifesto = $client->call('downloads.release_manifest', ['app' => 'mdm']);

No TypeScript, compile o plugin com tsc e rode o JavaScript no Node.js. O objeto exchange abaixo é fornecido pelo host e recebe texto JSON, retornando uma promessa de texto JSON.

import { Client, jsonTransport } from '@zerotrusted/forge-sdk';

const client = new Client(jsonTransport(exchange));
const manifest = await client.call('downloads.release_manifest', { app: 'mdm' });

O contrato está em contracts/service-call.schema.json. Trate erros como forbidden, invalid_input e unknown_operation sem repetir mutações automaticamente. Uma chamada síncrona não equivale à entrega de um evento. Execute os testes php titanArchitect-sdk/tests/gateway-wire.php e node titanArchitect-sdk/tests/gateway-wire.cjs na raiz do repositório para exercitar os dois clientes.

Valide um pacote FEX

O ZIP pode ter até 250 MB (262.144.000 bytes). O verificador aplica também um teto cumulativo de 1 GiB expandido, 512 arquivos, metadados de até 128 KiB por arquivo e limite de razão de compressão. Use caminhos relativos, sem links, diretórios explícitos ou nomes que só diferem em maiúsculas e minúsculas.

Inclua manifest.json, os arquivos declarados e um files.sha256 ordenado byte a byte por caminho. Cada linha do índice contém o SHA-256 em hexadecimal minúsculo, dois espaços, o caminho e um LF. Exclua o próprio índice e signature.sig do índice. Grave em signature.sig os 64 bytes da assinatura Ed25519 produzida sobre o índice exato. A chave pública fornecida ao operador tem 32 bytes.

php titansource/nucleo/pluginmanager/stage.php exemplo.fex public-key.bin /var/lib/titan/architect/staging

O diretório privado deve existir com modo 0700 fora da árvore da aplicação. O comando valida transmissão, assinatura e integridade e guarda o arquivo pelo SHA-256. Não extrai nem executa código. Aprovação de instalação, runtime e ativação continuam fora deste comando.