Módulo 3.4 - Plugin Development

🏗️ Scaffold de plugin

Ruflo gera o esqueleto inicial em segundos via plugins create. Você ganha estrutura completa: manifest, hooks, commands e exports prontos para customizar.

⚡Comando inicial

npx claude-flow@v3alpha plugins create my-plugin

Gera estrutura padrão:

my-plugin/
├── package.json
├── claude-flow.json    (manifest)
├── src/
│   ├── index.ts
│   ├── hooks/
│   └── commands/
└── tests/

📊O que vem pronto

TypeScript config com types do @claude-flow/plugins
Manifest exemplo em claude-flow.json
Test scaffold com Vitest
Build pipeline (tsup + esbuild)

🔧 Hooks, commands & exports

Um plugin pode contribuir três tipos de extensão. Tudo é declarado no claude-flow.json:

🔧claude-flow.json

{
  "name": "@me/my-plugin",
  "version": "1.0.0",
  "type": "integration",
  "hooks": ["pre-edit", "post-task"],
  "commands": ["my-command"],
  "exports": ["MyExport"],
  "permissions": ["memory", "network"]
}

Hooks

Interceptar lifecycle

Reagir a edits, comandos, sessões. Mesma API do módulo 3.3.

Commands

Subcomandos da CLI

Adicione npx claude-flow my-command. Útil para integrações de domínio.

Exports

APIs públicas

Funções/classes que outros plugins ou scripts podem importar via @me/my-plugin.

🔌 Integration: memory & neural

Plugins têm acesso às APIs internas de Ruflo: AgentDB, SONA, embeddings, hooks. Tudo via PluginContext injetado no handler.

🔌APIs disponíveis

export default async function activate(ctx: PluginContext) {
  // AgentDB memória
  await ctx.memory.store({ key: 'foo', value: 'bar' });
  const result = await ctx.memory.search('query');

  // SONA learning
  await ctx.neural.recordTrajectory(state, action, reward);

  // Embeddings
  const vec = await ctx.embeddings.embed('text');

  // Logger
  ctx.logger.info('plugin activated');
}

💡Permissões

Toda capability requer permissão declarada no manifest. memory, network, filesystem, neural. Usuários veem o que o plugin pode fazer antes de instalar.

🧪 Local testing

Antes de publicar, valide o plugin localmente. plugins install ./path faz install a partir do filesystem — útil para iteração rápida.

🧪Workflow de teste

1. Build do plugin:

cd my-plugin && npm run build

2. Install local:

npx claude-flow@v3alpha plugins install ./my-plugin

3. Verificar status:

npx claude-flow@v3alpha plugins list

4. Testar comandos:

npx claude-flow@v3alpha my-command --help

📊Iteração rápida

Watch mode — npm run dev para rebuild automático
Logs — --log-level debug para tracing detalhado
Reinstall — plugins reinstall para forçar reload

📤 Publish to IPFS

Plugins Ruflo são distribuídos via IPFS pinned em Pinata. Cada release recebe um CID imutável; o registry global aponta para o CID atual.

Build & package

Gera tarball

npm pack cria my-plugin-1.0.0.tgz com tudo necessário.

Upload Pinata

CID generation

plugins publish usa PINATA_API_JWT do .env. Retorna CID único.

Update registry

Discovery flow

Adiciona entry no registry IPFS, incrementa totalPlugins, atualiza LIVE_REGISTRY_CID.

⚠️Segurança

NUNCA commit PINATA_API_JWT no repo. Use .env (no .gitignore). E sempre source as credenciais em runtime, jamais hardcoded em scripts.

🏷️ Versioning & dist-tags

Plugins seguem Semantic Versioning. Use dist-tags (alpha, latest, v3alpha) para gerenciar canais de release.

🏷️SemVer básico

•MAJOR.MINOR.PATCH — 1.2.3
•MAJOR — breaking changes
•MINOR — features compatíveis
•PATCH — bug fixes
•Pre-release — 1.0.0-alpha.5, 1.0.0-rc.1

✓ FAZER

✓Atualizar TODOS os dist-tags pertinentes
✓Bump version antes de cada publish
✓Testar localmente antes de publicar
✓Manter CHANGELOG.md atualizado

✗ EVITAR

✗Esquecer dist-tag latest
✗Republicar mesma versão
✗Breaking change em PATCH
✗Hardcode de credenciais

⚡Comando dist-tag

npm dist-tag add @me/my-plugin@1.0.0 latest
npm dist-tag add @me/my-plugin@1.0.0-alpha.5 alpha
npm dist-tag ls @me/my-plugin

📋Resumo do Módulo

✓

Scaffold — plugins create gera estrutura completa em segundos

✓

Hooks/commands/exports — três tipos de extensão via manifest

✓

APIs internas — memory, neural, embeddings via PluginContext

✓

Local testing — install ./path para iteração rápida

✓

IPFS publish — Pinata + CID + registry update

✓

Versioning — SemVer + dist-tags (alpha, latest, v3alpha)

Próximo Módulo:

3.5 - Tópico avançado seguinte da Trilha 3

← Voltar para Trilha Próximo Módulo →