@oondemand/create-central-oon 0.3.8 → 0.3.10

package/docs/FRONTEND_PATTERNS.md

@@ -0,0 +1,77 @@
+# Padrões Frontend
+
+O frontend da Central deve ser declarativo. Shell, providers, rotas, menu, datagrid, formulários, documentos e esteiras pertencem ao `@oondemand/oon-core-front`.
+
+Para a lista completa de opções do manifesto, use `FRONTEND_MANIFEST_REFERENCE.md`.
+
+## Estrutura esperada
+
+```txt
+frontend/
+├── central.ui.json
+└── src/
+    ├── main.tsx
+    ├── collections/
+    ├── documents/
+    ├── pipelines/
+    ├── dashboards/
+    └── overrides/
+```
+
+## central.ui.json
+
+Use `central.ui.json` como entrada principal para declarar:
+
+- menu;
+- coleções;
+- campos exibidos;
+- filtros;
+- ações;
+- formulários;
+- documentos;
+- esteiras;
+- dashboards;
+- agrupamentos;
+- layout v2;
+- páginas por blocos;
+- renderers por chave.
+
+## Manifesto v1 e v2
+
+- Manifesto sem `schemaVersion` mantém compatibilidade v1.
+- Manifesto com `schemaVersion: 2` habilita composição por `layout`, `navigation`, `pages` e `blocks`.
+- Componentes React não devem ser serializados no JSON; use chaves e registre os componentes no `registry` em TypeScript.
+
+## Regras
+
+- Não recrie layout completo se o Core já renderiza.
+- Não duplique chamada REST manual se o SDK do Core já atende.
+- Não coloque regra de permissão apenas no frontend.
+- Não hardcode endpoints quando a metadata puder fornecer.
+- Não crie variações visuais fora do padrão sem necessidade real.
+- Use overrides pequenos, específicos e documentados.
+
+## Overrides
+
+Overrides são permitidos para:
+
+- campo especial;
+- ação específica;
+- card customizado;
+- cabeçalho customizado;
+- dashboard customizado;
+- integração visual pontual.
+
+Overrides não devem virar uma reimplementação do Core.
+
+## Experiência padrão
+
+A Central deve manter o padrão OonCore:
+
+- navegação consistente;
+- datagrids densos;
+- formulários claros;
+- feedback visual;
+- status por badges;
+- ações rastreáveis;
+- responsividade.

package/docs/OONCORE_ARCHITECTURE.md

@@ -0,0 +1,50 @@
+# Arquitetura OonCore
+
+O OonCore é a base para criar Centrais operacionais sob demanda com arquitetura padronizada, segura e evolutiva.
+
+A Central gerada não deve nascer como um sistema completo do zero. Ela deve nascer como uma camada de domínio que consome os recursos do Core.
+
+## Separação de responsabilidades
+
+```txt
+Central
+├── backend/   domínio, regras, validações, integrações e esteiras
+└── frontend/  declaração de telas, coleções, documentos e overrides
+
+OonCore Back
+├── boot Express
+├── Mongo/Mongoose
+├── autenticação
+├── RBAC
+├── CRUD metadata-driven
+├── auditoria
+├── triggers/hooks
+└── APIs padrão
+
+OonCore Front
+├── shell React
+├── providers
+├── roteamento
+├── menu
+├── datagrid
+├── formulários
+├── documentos
+├── esteiras
+└── SDK REST
+```
+
+## Modelo mini-monolítico
+
+Cada Central começa como um mini-monolito de negócio: pequeno, coeso, isolado e capaz de entregar valor rapidamente. Quando uma parte do domínio se tornar reutilizável, crítica ou independente, ela pode evoluir para conector, serviço compartilhado ou micro-serviço.
+
+## Fonte de verdade
+
+- Dados e regras ficam no backend.
+- Metadata operacional é exposta pelo backend.
+- Frontend renderiza a experiência a partir da metadata.
+- Permissões são decididas no backend.
+- Integrações são tratadas como conectores, mappings, triggers e esteiras de integração.
+
+## Objetivo do Codex
+
+O Codex deve acelerar a construção da Central usando a arquitetura existente. O objetivo não é gerar um app genérico, mas sim completar a camada de domínio com segurança e aderência ao Core.

package/docs/RBAC_SECURITY.md

@@ -0,0 +1,35 @@
+# RBAC e Segurança
+
+A segurança da Central deve ser aplicada no backend. O frontend pode ocultar ou exibir ações, mas não é a fonte de decisão.
+
+## Regras obrigatórias
+
+- Toda operação sensível deve validar usuário autenticado.
+- Toda alteração de dados deve validar permissão.
+- Toda ação de integração deve validar permissão e contexto.
+- Nunca confiar em `tenantId`, `appId`, `perfil` ou `roles` enviados livremente pelo frontend.
+- Segredos devem vir de variáveis de ambiente ou vault equivalente.
+- Logs não devem expor tokens, senhas, app keys ou dados sensíveis desnecessários.
+
+## RBAC
+
+Use o RBAC do Core para:
+
+- controlar acesso por app;
+- controlar perfis;
+- controlar ações;
+- filtrar funcionalidades;
+- proteger rotas;
+- permitir evolução de permissões sem reconstruir telas.
+
+## Checklist de segurança para Codex
+
+Antes de concluir uma alteração, confirme:
+
+- Existe validação de entrada?
+- Existe validação de permissão no backend?
+- Existe tratamento de erro?
+- A operação gera rastreabilidade?
+- Algum segredo foi colocado no código?
+- Algum dado sensível foi exposto no frontend?
+- O comportamento funciona para múltiplos usuários e múltiplos apps?

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@oondemand/create-central-oon",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",
     "directory": "packages/create-central-oon"
   },
-  "description": "Gerador de Centrais Oon com backend declarativo e frontend padrão Central Minexco: menu, datagrids, formulários e esteiras.",
+  "description": "Gerador de Centrais Oon com backend declarativo, frontend padrão e documentação interna OonCore para Codex.",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js"
@@ -19,6 +19,7 @@
     "bin",
     "src",
     "templates",
+    "docs",
     "README.md"
   ],
   "engines": {
@@ -30,7 +31,9 @@
     "central",
     "scaffold",
     "create",
-    "generator"
+    "generator",
+    "codex",
+    "docs"
   ],
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {

package/src/index.js

@@ -2,10 +2,13 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
 const { copyTemplate } = require("./render");
 
-const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
+const PACKAGE_ROOT = path.join(__dirname, "..");
+const TEMPLATES_DIR = path.join(PACKAGE_ROOT, "templates");
+const DOCS_DIR = path.join(PACKAGE_ROOT, "docs");
 
 const TEMPLATES = [
   { id: "basic", description: "Central mínima com uma coleção dinâmica (Pessoa)." },
@@ -52,6 +55,183 @@ function npmInstall(dir) {
   return !r.status && !r.error;
 }
 
+function readPackageVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+function listDocFiles(dir = DOCS_DIR, prefix = "") {
+  if (!fs.existsSync(dir)) return [];
+  const files = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const relative = path.join(prefix, entry.name);
+    const absolute = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...listDocFiles(absolute, relative));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(relative);
+    }
+  }
+
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+function docsHash(files = listDocFiles()) {
+  const hash = crypto.createHash("sha256");
+  for (const file of files) {
+    const normalized = file.split(path.sep).join("/");
+    hash.update(normalized);
+    hash.update("\n");
+    hash.update(fs.readFileSync(path.join(DOCS_DIR, file)));
+    hash.update("\n");
+  }
+  return hash.digest("hex");
+}
+
+function resolveCentralRoot(cwd = process.cwd()) {
+  const current = path.resolve(cwd);
+  const parent = path.dirname(current);
+
+  if (fs.existsSync(path.join(current, "backend")) && fs.existsSync(path.join(current, "frontend"))) {
+    return current;
+  }
+
+  if (
+    ["backend", "frontend"].includes(path.basename(current)) &&
+    fs.existsSync(path.join(parent, "backend")) &&
+    fs.existsSync(path.join(parent, "frontend"))
+  ) {
+    return parent;
+  }
+
+  return current;
+}
+
+function removeDir(dir) {
+  if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+}
+
+function copyDocs(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) {
+    throw new Error(`Diretório de documentação não encontrado: ${srcDir}`);
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const from = path.join(srcDir, entry.name);
+    const to = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDocs(from, to);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+function buildContext(files = listDocFiles()) {
+  const header = [
+    "# OonCore Contexto Consolidado para Codex",
+    "",
+    "> Arquivo gerado automaticamente por `create-central-oon docs --sync`.",
+    "> Não edite manualmente. A fonte de verdade está no pacote `@oondemand/create-central-oon` instalado.",
+    "",
+    "Este contexto consolida as regras mínimas para codificar Centrais Oon com segurança, usando o máximo dos recursos do OonCore.",
+    "",
+  ].join("\n");
+
+  const sections = files
+    .map((file) => {
+      const normalized = file.split(path.sep).join("/");
+      const content = fs.readFileSync(path.join(DOCS_DIR, file), "utf8").trim();
+      return [
+        "---",
+        "",
+        `<!-- source: ${normalized} -->`,
+        "",
+        content,
+        "",
+      ].join("\n");
+    })
+    .join("\n");
+
+  return `${header}\n${sections}`;
+}
+
+function buildManifest(files = listDocFiles()) {
+  return {
+    source: "@oondemand/create-central-oon",
+    version: readPackageVersion(),
+    generatedAt: new Date().toISOString(),
+    docsMode: "generated-cache",
+    docsHash: docsHash(files),
+    files: files.map((file) => file.split(path.sep).join("/")),
+  };
+}
+
+function syncDocs(opts = {}) {
+  const root = resolveCentralRoot(opts.cwd);
+  const outDir = path.join(root, ".ooncore");
+  const docsOutDir = path.join(outDir, "docs");
+  const files = listDocFiles();
+
+  if (!files.length) {
+    throw new Error("Nenhum arquivo .md encontrado em packages/create-central-oon/docs.");
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+  removeDir(docsOutDir);
+  copyDocs(DOCS_DIR, docsOutDir);
+
+  const codexSource = path.join(DOCS_DIR, "CODEX.md");
+  if (fs.existsSync(codexSource)) {
+    fs.copyFileSync(codexSource, path.join(outDir, "CODEX.md"));
+  }
+
+  fs.writeFileSync(path.join(outDir, "context.generated.md"), buildContext(files));
+  fs.writeFileSync(path.join(outDir, "manifest.json"), `${JSON.stringify(buildManifest(files), null, 2)}\n`);
+
+  console.log(`✔ Documentação OonCore sincronizada em ${path.relative(process.cwd(), outDir) || ".ooncore"}`);
+  console.log(`  Versão: ${readPackageVersion()}`);
+  console.log(`  Arquivos: ${files.length}`);
+}
+
+function checkDocs(opts = {}) {
+  const root = resolveCentralRoot(opts.cwd);
+  const manifestPath = path.join(root, ".ooncore", "manifest.json");
+  const version = readPackageVersion();
+  const files = listDocFiles();
+  const currentHash = docsHash(files);
+
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error("Documentação OonCore local não encontrada. Rode `npm run ooncore:docs`.");
+  }
+
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const problems = [];
+
+  if (manifest.source !== "@oondemand/create-central-oon") {
+    problems.push(`fonte esperada @oondemand/create-central-oon, encontrada ${manifest.source || "(vazia)"}`);
+  }
+
+  if (manifest.version !== version) {
+    problems.push(`versão local ${manifest.version || "(vazia)"} diferente da instalada ${version}`);
+  }
+
+  if (manifest.docsHash !== currentHash) {
+    problems.push("hash da documentação local diferente da documentação instalada");
+  }
+
+  if (problems.length) {
+    throw new Error(`Documentação OonCore desatualizada:\n- ${problems.join("\n- ")}\nRode \`npm run ooncore:docs\`.`);
+  }
+
+  console.log(`✔ Documentação OonCore atualizada (versão ${version}).`);
+}
+
 async function run(opts) {
   const template = TEMPLATES.find((t) => t.id === opts.template);
   if (!template) {
@@ -81,13 +261,19 @@ async function run(opts) {
   // 2. Overlay do template escolhido (vence sobre o _base).
   copyTemplate(path.join(TEMPLATES_DIR, template.id), targetDir, tokens);
 
+  // 3. Contexto local para Codex derivado da documentação da versão instalada.
+  syncDocs({ cwd: targetDir });
+
   console.log("✔ Arquivos gerados.");
 
   if (opts.install) {
     console.log("\n📦 Instalando dependências (best-effort)...");
+    const rootOk = fs.existsSync(path.join(targetDir, "package.json"))
+      ? npmInstall(targetDir)
+      : true;
     const backOk = npmInstall(path.join(targetDir, "backend"));
     const frontOk = npmInstall(path.join(targetDir, "frontend"));
-    if (!backOk || !frontOk) {
+    if (!rootOk || !backOk || !frontOk) {
       console.warn(
         "\n⚠ npm install falhou em um dos projetos (esperado se os pacotes @oondemand/* ainda não foram publicados). Rode manualmente depois."
       );
@@ -103,7 +289,11 @@ function printNextSteps(tokens, opts) {
 ✅ Central "${tokens.name}" pronta.
 
 Próximos passos:
-${cd}  # Backend (só domínio — models/validations/triggers/...)
+${cd}  # Sincronizar/validar documentação local do Core para Codex
+  npm run ooncore:docs
+  npm run ooncore:docs:check
+
+  # Backend (só domínio — models/validations/triggers/...)
   cd backend && cp .env.example .env && npm run dev
 
   # Frontend (só declaração — central.ui.json)
@@ -114,4 +304,13 @@ Edite backend/src/models e frontend/central.ui.json para evoluir a Central.
 `);
 }
 
-module.exports = { run, listTemplates, toSlug, toPascal, toTitle };
+module.exports = {
+  run,
+  listTemplates,
+  toSlug,
+  toPascal,
+  toTitle,
+  syncDocs,
+  checkDocs,
+  resolveCentralRoot,
+};

package/templates/_base/README.md

@@ -1,7 +1,6 @@
 # __NAME__
 
-Central Oon gerada com `create-central-oon`. É composta por dois projetos
-mínimos que consomem o Core:
+Central Oon gerada com `create-central-oon`. É composta por dois projetos mínimos que consomem o Core:
 
 - **backend/** — só domínio (`src/models`, `validations`, `triggers`, …).
   Sobe com `oonCore-back dev`. Toda a infra (boot, db, auth, RBAC, metadata,
@@ -10,9 +9,26 @@ mínimos que consomem o Core:
   dev`. Shell, providers, roteamento, auth e telas vêm do
   `@oondemand/oon-core-front`, renderizados a partir do `/core/metadata` do back.
 
+## Documentação local do OonCore
+
+A pasta `.ooncore/` é gerada automaticamente a partir da versão instalada do pacote `@oondemand/create-central-oon`.
+
+Ela serve como contexto local para o Codex codificar sem depender de site externo.
+
+```bash
+npm run ooncore:docs        # sincroniza .ooncore/
+npm run ooncore:docs:check  # valida versão/hash da documentação local
+```
+
+Não edite `.ooncore/context.generated.md` manualmente. Atualize o pacote e rode o sync.
+
 ## Rodando
 
 ```bash
+# raiz da Central
+npm install
+npm run ooncore:docs:check
+
 # backend
 cd backend && cp .env.example .env && npm install && npm run dev
 
@@ -24,4 +40,5 @@ cd frontend && cp .env.example .env && npm install && npm run dev
 
 1. Crie models em `backend/src/models` (só schema + CRUD).
 2. Declare as telas em `frontend/central.ui.json` (coleções/esteiras/documentos).
-3. O resto — grid, form, rotas, menu — é montado pelo Core automaticamente.
+3. Use validations, triggers, hooks, mappings e integrations para regras e processos.
+4. O resto — grid, form, rotas, menu — é montado pelo Core automaticamente.

package/templates/_base/backend/package.json

@@ -12,6 +12,6 @@
     "deploy": "oonCore-back deploy"
   },
   "dependencies": {
-    "@oondemand/oon-core-back": "^0.3.8"
+    "@oondemand/oon-core-back": "^0.3.10"
   }
 }

package/templates/_base/frontend/package.json

@@ -10,7 +10,7 @@
     "sync:metadata": "oonCore-front sync:metadata"
   },
   "dependencies": {
-    "@oondemand/oon-core-front": "^0.3.8",
+    "@oondemand/oon-core-front": "^0.3.10",
     "@chakra-ui/react": "^3.13.0",
     "@emotion/react": "^11.14.0",
     "@tanstack/react-query": "^5.65.0",

package/templates/_base/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Central Oon __NAME__ gerada com create-central-oon.",
+  "scripts": {
+    "ooncore:docs": "create-central-oon docs --sync",
+    "ooncore:docs:check": "create-central-oon docs --check",
+    "dev:backend": "npm run dev --prefix backend",
+    "dev:frontend": "npm run dev --prefix frontend"
+  },
+  "devDependencies": {
+    "@oondemand/create-central-oon": "^0.3.8"
+  }
+}