@oondemand/create-central-oon 0.7.4 → 0.7.6

package/src/example.js

@@ -0,0 +1,39 @@
+"use strict";
+const fs = require("node:fs");
+const path = require("node:path");
+const { resolveCentralRoot } = require("./index");
+const { listFiles } = require("./conformance");
+
+// Explicit opt-in after generating the canonical base. Never overwrite an App.
+function installExample({ cwd = process.cwd() } = {}) {
+  const root = resolveCentralRoot(cwd);
+  const source = path.join(__dirname, "../examples/first-journey");
+  const files = listFiles(source);
+  const manifestPath = path.join(root, "central.app.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  if (manifest.tenancyModel !== "single_tenant" || manifest.deploymentMode !== "dedicated") throw new Error("Exemplo requer single_tenant dedicado da base oficial.");
+  for (const file of files) {
+    if (fs.existsSync(path.join(root, file))) throw new Error(`Exemplo não sobrescreve ${file}. Use um App recém-gerado.`);
+  }
+  const composition = ["routes.tsx", "navigation.ts"];
+  for (const name of composition) {
+    const relative = `frontend/src/app/${name}`;
+    const base = fs.readFileSync(path.join(__dirname, "../templates/_base", relative), "utf8");
+    if (fs.readFileSync(path.join(root, relative), "utf8") !== base) throw new Error(`Exemplo requer composição original: ${relative}. Nenhum arquivo foi alterado.`);
+  }
+  manifest.capabilities = [...new Set([...manifest.capabilities, "core.secrets"])];
+  manifest.capabilitySettings = { ...manifest.capabilitySettings, "core.secrets": { enabled: true } };
+  const permissions = ["segredos.manage", "pessoas.read", "pessoas.write", "tickets.read", "tickets.write", "jornada.write", "integracao.test", "contratos.read", "contratos.write", "parcelas.read", "parcelas.write", "documentos.read", "documentos.write", "pdf.render"];
+  manifest.rbac.permissions = [...new Set([...manifest.rbac.permissions, ...permissions])];
+  for (const file of files) {
+    fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
+    fs.copyFileSync(path.join(source, file), path.join(root, file));
+  }
+  const routes = path.join(root, "frontend/src/app/routes.tsx");
+  fs.writeFileSync(routes, fs.readFileSync(routes, "utf8").replace('import { HomePage }', 'import { SecretsPage } from "../pages/SecretsPage";\nimport { NativeResourcesPage } from "../pages/NativeResourcesPage";\nimport { JourneyPage } from "../pages/JourneyPage";\nimport { HomePage }').replace('  { path: "/", component: HomePage },', '  { path: "/", component: HomePage },\n  { path: "/jornada", component: JourneyPage },\n  { path: "/recursos", component: NativeResourcesPage },\n  { path: "/segredos", component: SecretsPage },'));
+  const navigation = path.join(root, "frontend/src/app/navigation.ts");
+  fs.writeFileSync(navigation, fs.readFileSync(navigation, "utf8").replace('  { label: "Início", href: "/", order: 10 },', '  { label: "Início", href: "/", order: 10 },\n  { label: "Primeira jornada", href: "/jornada", order: 20 },\n  { label: "Recursos nativos", href: "/recursos", order: 30 },\n  { label: "Segredos", href: "/segredos", order: 40 },'));
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  console.log("Exemplo instalado em /jornada, com navegação, endpoints e permissões. Siga FIRST_JOURNEY.md.");
+}
+module.exports = { installExample };

package/src/index.js

@@ -47,6 +47,21 @@ function readPackageVersion() {
   return pkg.version;
 }
 
+// Documentation examples follow the installed release, including docs sync/check.
+// Hash the rendered bytes so consumers can verify the exact generated cache.
+function renderDoc(content) {
+  const version = readPackageVersion();
+  const [major, minor] = version.split(".").map(Number);
+  return content
+    .replace(/__OONCORE_VERSION__/g, version)
+    .replace(/__OONCORE_LINE__/g, `${major}.${minor}`)
+    .replace(/__OONCORE_RANGE__/g, `>=${major}.${minor}.0 <${major}.${minor + 1}.0`);
+}
+
+function readDoc(file) {
+  return renderDoc(fs.readFileSync(path.join(DOCS_DIR, file), "utf8"));
+}
+
 function listDocFiles(dir = DOCS_DIR, prefix = "") {
   if (!fs.existsSync(dir)) return [];
   const files = [];
@@ -71,7 +86,7 @@ function docsHash(files = listDocFiles()) {
     const normalized = file.split(path.sep).join("/");
     hash.update(normalized);
     hash.update("\n");
-    hash.update(fs.readFileSync(path.join(DOCS_DIR, file)));
+    hash.update(readDoc(file));
     hash.update("\n");
   }
   return hash.digest("hex");
@@ -95,9 +110,9 @@ function rootAgentEntrypoint() {
   return [
     "# OonCore — entrada para IA/Agents",
     "",
-    "Leia o contrato canônico completo em [docs/AGENTS.md](docs/AGENTS.md).",
+    "Leia a entrada curta em [docs/AGENTS.md](docs/AGENTS.md) e consulte apenas a tarefa necessária.",
     "",
-    "Confira \`.ooncore/manifest.json\` e execute \`npm run ooncore:docs:check\` antes de alterar o App.",
+    "Execute \`npm run check\` para validar cache e conformidade; regenere o cache somente pelo comando oficial.",
     "",
   ].join("\n");
 }
@@ -105,7 +120,7 @@ function rootAgentEntrypoint() {
 function entrypointContents(files = listDocFiles()) {
   return {
     "AGENTS.md": rootAgentEntrypoint(),
-    "CODEX.md": fs.readFileSync(path.join(DOCS_DIR, "CODEX.md"), "utf8"),
+    "CODEX.md": readDoc("CODEX.md"),
     "context.generated.md": buildContext(files),
   };
 }
@@ -168,7 +183,9 @@ function copyDocs(srcDir, destDir) {
     if (entry.isDirectory()) {
       copyDocs(from, to);
     } else if (entry.isFile()) {
-      fs.copyFileSync(from, to);
+      fs.writeFileSync(to, entry.name.endsWith(".md")
+        ? renderDoc(fs.readFileSync(from, "utf8"))
+        : fs.readFileSync(from));
     }
   }
 }
@@ -180,14 +197,14 @@ function buildContext(files = listDocFiles()) {
     "> 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 os contratos públicos para Codex, ChatGPT, Kimi, Manus ou qualquer Agent compatível.",
+    "Compilação opcional para consulta. Comece por docs/OON_APP_AGENT_GUIDE.md e docs/TASK_INDEX.md; não é necessário ler este arquivo inteiro.",
     "",
   ].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();
+      const content = readDoc(file).trim();
       return [
         "---",
         "",
@@ -232,7 +249,7 @@ function syncDocs(opts = {}) {
 
   fs.writeFileSync(path.join(outDir, "AGENTS.md"), rootAgentEntrypoint());
   const codexSource = path.join(DOCS_DIR, "CODEX.md");
-  if (fs.existsSync(codexSource)) fs.copyFileSync(codexSource, path.join(outDir, "CODEX.md"));
+  if (fs.existsSync(codexSource)) fs.writeFileSync(path.join(outDir, "CODEX.md"), readDoc("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`);
@@ -299,7 +316,7 @@ function checkDocs(opts = {}) {
     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}).`);
+  if (!opts.quiet) console.log(`✔ Documentação OonCore atualizada (versão ${version}).`);
 }
 
 async function run(opts) {
@@ -350,15 +367,13 @@ function printNextSteps(tokens, opts) {
 ✅ Central "${tokens.name}" pronta.
 
 Próximos passos:
-${cd}  # Sincronizar/validar documentação local do Core para Agents
-  npm run ooncore:docs
-  npm run ooncore:docs:check
-
-  # Runtime local desconectado (backend + frontend)
+${cd}  # Instale as dependências se usou --no-install ou se a instalação falhou.
+  # Configure MongoDB e os .env conforme README.md.
   npm run dev
 
-O backend expõe /core/metadata; o frontend renderiza as telas a partir dele.
-Crie páginas, componentes e features em frontend/src e modele o domínio no backend.
+Siga .ooncore/docs/OON_APP_AGENT_GUIDE.md: gerar, executar, implementar uma
+jornada, validar e publicar pelo fluxo existente. Para alterar, consulte
+.ooncore/docs/TASK_INDEX.md. npm run check valida cache e conformidade.
 `);
 }
 

package/templates/_base/README.md

@@ -1,62 +1,33 @@
 # __NAME__
 
-App Oon code-first gerado com `create-central-oon`.
+App Oon code-first gerado com `create-central-oon`. Comece pela entrada curta `.ooncore/AGENTS.md` e pelo roteiro `.ooncore/docs/OON_APP_AGENT_GUIDE.md`; escolha referências em `.ooncore/docs/TASK_INDEX.md` conforme a tarefa. Não é necessário ler o contexto consolidado nem fonte privada.
 
-## Comece aqui
+## Executar
 
-A pasta `.ooncore/` contém o contrato público versionado para criar e customizar este App. Um Agent deve usar somente esta árvore do projeto: não é necessário consultar fonte privada do OonCore, `node_modules` ou outros Apps.
-
-1. Leia `.ooncore/AGENTS.md`.
-2. Rode `npm run ooncore:docs:check`.
-3. Siga `.ooncore/docs/OON_APP_AGENT_GUIDE.md`.
-4. Consulte `.ooncore/docs/CAPABILITIES.md` e o guia específico da tarefa.
-
-Se faltar um contrato, registre a lacuna documental em vez de inventar API ou infraestrutura.
-
-## Fronteira arquitetural
-
-- `central.app.json` declara identidade, `appKind`, tenant, acesso, módulos, capabilities funcionais e compatibilidade;
-- `oon.deploy.json` declara runtime e dependências de infraestrutura da publicação;
-- `backend/src/models` e demais extensões code-first contêm o domínio;
-- `backend/central.domain.json` é opcional quando o projeto adota o contrato declarativo documentado;
-- `frontend/src/app` compõe rotas, navegação, layouts e temas;
-- `frontend/src/{pages,components,features}` contém a experiência local;
-- `backend/central.config.js` fica reservado a extensões documentadas de runtime;
-- `frontend/src/main.tsx` chama `startOonApp`.
-
-Autenticação, guards, shell, RBAC, metadata, CRUD e infraestrutura pertencem ao OonCore.
-
-## Documentação e conformidade
+Requer Node compatível com os pacotes e MongoDB local. Ajuste `MONGO_URI` para um banco de desenvolvimento.
 
 ```bash
-npm run ooncore:docs        # sincroniza .ooncore/
-npm run ooncore:docs:check  # valida versão/hash do cache local
-npm run ooncore:conformance # valida a fronteira da Central
-npm run check               # executa os gates locais
-npm test
+npm install
+npm install --prefix backend
+npm install --prefix frontend
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
+npm run dev
 ```
 
-`.ooncore/` é um cache regenerável da documentação publicada no pacote. Não edite `context.generated.md` manualmente; versione a pasta junto com o App para que humanos e Agents recebam o mesmo contrato.
+O runtime local funciona em loopback com sessão técnica; não cadastra recursos na Plataforma. Capabilities dependentes da Plataforma falham fechado quando indisponíveis.
+
+## Entregar a primeira jornada
 
-## Rodando
+Implemente página, navegação, endpoint e permissão usando `.ooncore/docs/PUBLIC_CONTRACTS.md`. Domínio fica em `backend/src`; `backend/central.domain.json` é opcional. Composição de UX fica em `frontend/src/app` e `frontend/src/pages`. `central.app.json` declara identidade e acesso; `oon.deploy.json` declara requisitos de publicação.
 
 ```bash
-npm install
 npm run check
-
-cp backend/.env.example backend/.env
-cp frontend/.env.example frontend/.env
-npm run dev
+npm run build --prefix frontend
 ```
 
-O comando inicia backend e frontend exclusivamente em loopback, abre uma sessão local aleatória e não consulta nem cria recursos na plataforma. Capabilities de plataforma falham fechado quando não resolvidas. Não implemente autenticação, ativação ou infraestrutura paralela.
-
-## Evoluindo a Central
+`check` inclui cache documental e conformance. Execute os testes relevantes quando declarados; a base neutra não contém script raiz `test`. Prove a jornada, versione código/manifestos/lockfiles/cache e publique pelo fluxo existente do Workspace/Plataforma. Registre o commit e a validação autenticada em Dev. Build, publicação e homologação são estados distintos.
 
-1. Modele o domínio por exports públicos em `backend/src` ou adote o manifesto declarativo conforme `BACKEND_DOMAIN_MANIFEST.md`.
-2. Crie rotas, páginas, componentes, layouts e temas nos pontos documentados.
-3. Declare capabilities no manifesto indicado pelo guia dedicado.
-4. Use validações, triggers, hooks, mappings e regras somente para comportamento específico do negócio.
-5. Execute `npm run check` e `npm test` antes de abrir o PR.
+Lacuna documental: registre, use extensão pública adequada no App e continue as partes independentes; não invente APIs nem remova autenticação, autorização ou isolamento. POC não exige roadmap completo nem matriz final de perfis. Não reimplemente nem homologue novamente os serviços já homologados da Plataforma.
 
-O OonCore fornece a fundação; o App implementa sua experiência e seu domínio.
+`.ooncore/` é cache gerado: atualize a fonte do pacote e use `npm run ooncore:docs`; nunca edite manualmente. Upgrade coordenado está em `.ooncore/docs/CORE_UPGRADE.md`.

package/templates/_base/backend/package.json

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

package/templates/_base/frontend/package.json

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

package/templates/_base/frontend/src/app/app.tsx

@@ -18,8 +18,8 @@ export const app = defineOonApp({
     meusAppsUrl: import.meta.env.DEV ? undefined : import.meta.env.VITE_MEUS_APPS_URL,
   },
   runtimeMode: import.meta.env.DEV ? "local" : "platform",
-  routes,
-  navigation,
+  routes: [...routes],
+  navigation: [...navigation],
   theme,
   shell: { shell: "default" },
 });

package/templates/_base/frontend/src/pages/HomePage.tsx

@@ -1,9 +1,9 @@
 import { Stack, Text } from "@chakra-ui/react";
-import { CorePage, CorePageHeader, CoreStatusPanel, CoreSummaryCards } from "@oondemand/oon-core-front/ui";
+import { CorePageHeader, CoreStatusPanel, CoreSummaryCards } from "@oondemand/oon-core-front/ui";
 
 export function HomePage() {
   return (
-    <CorePage>
+    <Stack gap={6} p={6}>
       <CorePageHeader
         title="Boas-vindas ao __NAME__"
         description="A fundação técnica está pronta para receber a experiência e o domínio do app."
@@ -20,6 +20,6 @@ export function HomePage() {
         />
         <Text color="text.muted">Menus, rotas, layouts e temas ficam em src/app e podem combinar componentes locais com blocos públicos do OonCore.</Text>
       </Stack>
-    </CorePage>
+    </Stack>
   );
 }

package/templates/_base/package.json

@@ -7,12 +7,12 @@
     "ooncore:docs": "create-central-oon docs sync",
     "ooncore:docs:check": "create-central-oon docs check",
     "ooncore:conformance": "create-central-oon conformance",
-    "check": "npm run ooncore:docs:check && npm run ooncore:conformance",
+    "check": "create-central-oon doctor",
     "dev": "create-central-oon dev",
     "dev:backend": "npm run dev --prefix backend",
     "dev:frontend": "npm run dev --prefix frontend"
   },
   "devDependencies": {
-    "@oondemand/create-central-oon": "0.7.4"
+    "@oondemand/create-central-oon": "0.7.6"
   }
 }