@oondemand/create-central-oon

Gerador de Centrais Oon declarativas. Cria backend e frontend prontos para consumir @oondemand/oon-core-back e @oondemand/oon-core-front, sem copiar shell, autenticação, páginas genéricas ou infraestrutura para a Central.

Uso

npx create-central-oon central-transtour
npx create-central-oon central-transtour --template=servicos-tomados
npx create-central-oon --list

Aliases: o binário também responde por scaffold-central-oon.

Contrato central.app.json

Toda Central gerada possui um manifesto raiz com identidade e capabilities:

{
  "$schema": "./node_modules/@oondemand/create-central-oon/schemas/central.app.schema.json",
  "schemaVersion": 1,
  "id": "central-exemplo",
  "name": "Central Exemplo",
  "slug": "central-exemplo",
  "appKind": "member-central",
  "modules": {
    "collections": true,
    "documents": false,
    "pipelines": false,
    "integrations": false,
    "omie": false,
    "assistants": false,
    "currencies": false
  },
  "capabilities": ["core.collections"],
  "compatibility": {
    "core": {
      "minVersion": "0.3.45",
      "maxVersionExclusive": "0.4.0"
    }
  }
}

O schema versionado é publicado no pacote em:

@oondemand/create-central-oon/schemas/central.app.schema.json

Responsabilidades do manifesto:

• identidade estável (id, name, slug);
• perfil arquitetural (appKind);
• módulos e capabilities habilitados;
• faixa compatível do OonCore;
• metadados declarativos de ativação.

backend/central.config.js fica reservado a extensões excepcionais de runtime. Em Centrais member-central e portal-cockpit, identidade, módulos e autenticação não podem ser reintroduzidos nesse arquivo. O token local de desenvolvimento é validado pelo próprio OonCore por DEV_TOKEN.

Verificação de conformidade

Na raiz da Central:

npm run ooncore:conformance

ou:

npx create-central-oon conformance
npx create-central-oon conformance --json

O comando falha quando encontra, entre outros desvios:

• ausência ou incompatibilidade de central.app.json;
• transformações ou registries no bootstrap do frontend;
• páginas genéricas e extensões executáveis locais;
• identidade ou autenticação reintroduzida em central.config.js;
• models técnicos de integração;
• workers, runtimes, locks, clients Omie ou registries locais;
• patches de métodos do Mongoose;
• arquivos com extensões fora da allowlist.

A CI de uma Central deve executar o comando antes do build e da publicação.

Documentação interna para Codex

O pacote inclui documentação canônica em docs/. Ao criar uma Central, o CLI gera .ooncore/ como cache local da documentação da versão instalada.

npm run ooncore:docs
npm run ooncore:docs:check

A pasta .ooncore/ não é fonte de verdade; ela pode ser regenerada a partir do pacote npm.

Templates funcionais

| Template | O que gera | | --- | --- | | basic | Uma coleção dinâmica (Pessoa). | | omie-sidecar | Estrutura declarativa inicial para mapping Omie. | | servicos-tomados | Prestadores e esteira por status. | | servicos-prestados | Clientes e esteira por etapa. | | pedidos-marketplace | Catálogo e esteira de pedidos. | | documentos-fiscais | Documento fiscal com aprovação. | | multi-moedas | Moedas e cotações. |

Estrutura gerada

<central>/
├── central.app.json            # identidade, appKind, módulos e capabilities
├── package.json                # docs, conformance e comandos locais
├── .ooncore/                   # cache regenerável da documentação
├── backend/
│   ├── central.config.js       # somente extensão excepcional de runtime
│   ├── central.domain.json     # domínio declarativo
│   └── src/{validations,triggers,hooks,mappings,rules}/
└── frontend/
    ├── central.ui.json         # telas, formulários, grids e esteiras
    └── src/main.tsx            # bootstrap mínimo gerado

O bootstrap gerado importa central.app.json e central.ui.json e chama startCentralFromManifest. Não deve transformar manifestos, registrar componentes padrão nem conhecer regras de um cliente.

Próximos passos

cd <central>
npm run check

cd backend && cp .env.example .env && npm run dev
cd ../frontend && cp .env.example .env && npm run dev

Evoluir a Central significa declarar domínio, UI, mappings e regras específicas. O OonCore implementa como a aplicação funciona.