KoBa-beep/ClaudeCode-Skill

Drivers NEEO com meta

meta (jac459/meta) é um motor Node.js que lê arquivos JSON de dispositivos da sua pasta active/ e transforma cada um em um driver do SDK NEEO registrado com o cérebro NEEO local. Você descreve o dispositivo em JSON; você não escreve JavaScript (exceto pequenas expressões DYNAMIK).

Idioma: escreva para o usuário no idioma dele. Chaves JSON, palavras-chave do motor, nomes de botões e strings de log permanecem exatamente como documentados aqui (inglês).

Escopo: apenas o SDK NEEO pré-aquisição, o cérebro local e o meta são relevantes. Ignore material Control4 e a nuvem NEEO (desligada).

Regras básicas (nunca pule)

1. Nunca invente uma chave JSON ou tipo de comando. Se um recurso não estiver nas referências, diga isso e ofereça uma alternativa: um serviço complementar (Node-RED + MQTT, ou uma pequena ponte REST local, veja references/companion-services.md), um comando cli ou uma cadeia de botões ocultos.
2. JSON puro: sem comentários, sem vírgulas finais, aspas duplas. Valide com python3 -m json.tool arquivo.json e python3 scripts/check_driver.py arquivo.json.
3. Tipos de comando são sensíveis a maiúsculas/minúsculas: http-get, http-rest, http-post, http-get-soap, static, cli, repl, webSocket, socketIO, jsontcp, mqtt, wol, mDNS, android.
4. Aumente version sempre que um componente visível for adicionado. O cérebro apenas adiciona componentes; renomear ou remover um exige excluir e readicionar o dispositivo no aplicativo NEEO (receitas e atalhos devem ser refeitos). Mesmo um aumento às vezes não é suficiente em um dispositivo instalado: verifique o cérebro (references/debugging.md).
5. Nomes (chaves) de rótulos, interruptores, controles deslizantes, imagens e sensores: apenas letras e dígitos. Um espaço ou símbolo quebra o link do sensor ("sensor": null no cérebro) e o controle remoto trava na sincronização assim que o componente é usado como atalho. O texto do label exibido é livre. Nomes de botões podem conter espaços, mas evite + e acentos (DISNEY PLUS, rótulo Disney+).
6. Nunca escreva "" em uma variável vinculada a um rótulo: no meta v1.2.0, um rótulo que vai de um texto de volta para "" para o meta. Escreva " " (ou um fallback legível). Inicialize variáveis de rótulo com " " também, como um hábito.
7. Sanitize todo texto externo antes que ele alcance um rótulo: " -> ', \ -> /, caracteres de controle -> espaço, $ -> ＄ (largura total). Faça isso no driver e na fonte.
8. Listeners iniciam uma vez por sessão, através da guarda ListenerOn + botão oculto __LISTEN conectado a cada controle visível. Nunca confie apenas em POWER ON, e nunca chame __CLEANUP em um listener mqtt (references/listeners-and-state.md).
9. Eventos sobre polling (webSocket, socketIO, mqtt). Se for polling, pooltime >= 3000.
10. $Result é sempre uma string, "undefined" em caso de falha: proteja cada JSON.parse. Um botão recebe um escalar (ok); um alimentador de ação de diretório recebe ["ok"].
11. Nomes de variáveis: nunca use um nome que seja prefixo de outro; $Var colado a letras é lido como uma variável diferente.
12. Segurança: DYNAMIK e cli executam código no host meta. Nenhum segredo codificado permanentemente em um driver destinado a ser compartilhado; meta não deve ser executado como root/admin.
13. Alterações irreversíveis precisam de consentimento: adicionar componentes visíveis (por exemplo, DIGIT 0-9) não pode ser desfeito sem reinstalar o dispositivo. Pergunte primeiro.
14. Entregáveis separados: um driver meta é um objeto JSON (começa com {, nunca -flow em seu nome, vai em active/); um fluxo Node-RED é uma lista JSON (começa com [, sempre nomeado *-flow.json, importado no Node-RED).
15. Em template, dynamicname e dynamicid são obrigatórios; dynamicid deve ser estável (endereço MAC ou ID de hardware em vez de um IP DHCP).

Fluxo de trabalho

1. Colete o que precisa (faça no máximo 3 perguntas direcionadas por vez): modelo exato do dispositivo; seu protocolo de controle ou API (HTTP/REST, WebSocket, TCP bruto, MQTT, apenas IR, Android TV...); IP fixo ou não e um ID estável (MAC); o que deve ser controlado e qual estado deve ser exibido; versão do meta e onde o meta é executado (Pi com pm2, Docker...); se um broker MQTT e Node-RED estão disponíveis. Procure pela documentação oficial da API do dispositivo quando existir.
2. Escolha o tipo NEEO (references/driver-anatomy.md, seção tipos e botões reconhecidos) e o padrão de descoberta (references/discovery.md): dispositivo único estático, IP digitado pelo usuário, mDNS ou hub.
3. Comece a partir de um esqueleto em assets/: skeleton-static.json (um dispositivo, endereço fixo) ou skeleton-register-ip.json (o usuário digita o IP). Reutilize padrões comprovados de references/patterns.md.
4. Decida onde a lógica reside. Dispositivo HTTP ou WebSocket simples: tudo no driver. Protocolo binário ou stateful (TCP bruto, sessões persistentes, emparelhamento, estado irregular): coloque um serviço complementar no meio, com comandos HTTP rápidos e estado enviado como uma mensagem MQTT retida (references/companion-services.md).
5. Verifique antes de entregar:
   • python3 -m json.tool driver.json então python3 scripts/check_driver.py driver.json (nomes, valores vazios de rótulo, tipos, versão, guarda, polling...);
   • node scripts/simulate_guard.js driver.json quando o driver tiver listeners (conta __INITIALISE / __CLEANUP ao longo das sessões);
   • avalie expressões DYNAMIK complicadas no Node com as regras reais de substituição (references/logic-and-commands.md);
   • releia references/pitfalls.md.
6. Entregue nesta ordem: resumo (dispositivo, protocolo, tipo NEEO, padrão de descoberta, coberto / não coberto); o arquivo JSON completo e validado com um nome de arquivo explícito; etapas de implantação (copiar para active/, reiniciar meta, adicionar o dispositivo no aplicativo NEEO, visibilidade de receitas e atalhos a criar); plano de teste (botões a experimentar, resultado esperado, linhas de log a procurar); suposições não verificadas no dispositivo real; próxima iteração. Para projetos com vários arquivos (driver + fluxo + serviço): ordem das operações, um marcador de versão em cada entregável e como verificar qual versão está instalada. Sempre diga o que não foi testado no dispositivo real.

Mapa de referências (leia apenas o que a tarefa precisa)

Arquivo	Leia quando
references/meta-engine.md	Arquitetura, instalação, pastas, reinicialização, níveis de log, tópicos MQTT expostos pelo meta, hospedagem Docker/NAS, bugs conhecidos do meta v1.2.0
references/driver-anatomy.md	Chaves de nível superior, tipos de dispositivos NEEO e nomes de botões reconhecidos, variáveis, substituição $, DYNAMIK, componentes de UI
references/logic-and-commands.md	evalwrite, evaldo, evalnext, botões especiais, cada tipo de comando, queryresult / JSONPath
references/listeners-and-state.md	Listeners, a guarda ListenerOn, comportamento de listener MQTT, fontes de estado irregulares, reconstruções de instância
references/discovery.md	discover, register, template, initcommandset, mDNS, entrada de IP, hubs, emparelhamento
references/directories.md	Listas, alimentadores, campos item*, ações, navegação em vários níveis
references/patterns.md	Receitas comprovadas: volume, energia, barra de status, persistência, cadeias, loops, caminho de fallback, iniciador de aplicativos, imagem de arte
references/pitfalls.md	Leitura obrigatória antes de entregar
references/debugging.md	Leitura de dados do meta, Mosquitto e cérebro, assinaturas de log, isolamento de um link, teste em sandbox
references/companion-services.md	Pontes Node-RED e MQTT, pontes REST locais, lições do Apple TV / pyatv
references/community-drivers.md	Drivers de referência para imitar, mapeamento SDK <-> meta, fontes

Marcas de evidência usadas nas referências

[código v1.2.0] lido no código-fonte do meta (branch Release); [observado] visto em drivers reais ou instalações reais; [a verificar] dedução ainda não testada. Quando um comportamento é importante e não está marcado, verifique o código do meta (git clone --depth 1 --branch Release https://github.com/jac459/meta) em vez de adivinhar, e diga qual você fez.