forlogic-core 3.0.10 → 4.0.0

package/docs/design-system/knowledge/RULES.md

@@ -0,0 +1,217 @@
+# forlogic-core — DS Knowledge (padrão para novos projetos)
+
+> Cole este arquivo inteiro no **Workspace Knowledge** do projeto consumidor.
+> Ele é a fonte única de verdade para construir uma aplicação fiel ao Design System.
+> Fonte das regras: `@Admin docs/design-system/knowledge/RULES.md`.
+> Detalhes por componente: `@Admin docs/design-system/<categoria>.md` e `.../patterns/<padrão>.md`.
+
+---
+
+## 1. Regras invioláveis
+
+| # | Regra |
+|---|-------|
+| 1 | **Lib-first** — antes de criar qualquer componente visual, procurar em `forlogic-core`. Criar novo só se não existir equivalente. |
+| 2 | **Todo import visual vem de `forlogic-core`** — nunca de `@radix-ui/*`, `react-day-picker`, `recharts`, `cmdk` diretamente. |
+| 3 | **Zero cor literal** — proibido `text-white`, `bg-black`, `bg-[#...]`, `text-gray-500`. Somente tokens semânticos (`bg-background`, `text-muted-foreground`, `border-border`). |
+| 4 | **Variante de erro = `danger`**, nunca `destructive`, em Button/Badge/Alert/Dialog. |
+| 5 | **Ícones = `lucide-react`**. Exceção única: `IconPicker` (Material Symbols). |
+| 6 | **i18n** — `useTranslation` importado de `forlogic-core`, nunca de `react-i18next`. |
+| 7 | **Supabase** — cliente via `getSupabaseClient()` de `forlogic-core`; toda query com `.schema('<schema-do-projeto>')` explícito. |
+| 8 | **Sem DELETE físico** — soft delete com `deleted_at`. |
+| 9 | **RLS `TO authenticated`** — nunca conceder `anon` sem justificativa comentada na migration (`-- ANON: motivo`) e registrada no security memory. |
+| 10 | **Sem role em client storage** — nunca localStorage/sessionStorage para permissão; roles em tabela separada + função `SECURITY DEFINER`. |
+| 11 | **Scroll único** — root `h-screen overflow-hidden`; um só container rolável (`flex-1 min-h-0 overflow-y-auto`). |
+| 12 | **`VITE_SUPABASE_PK_OVERRIDE`** obrigatória no `.env` quando `backend="supabase"` — nunca remover. |
+| 13 | **Variantes de componente** seguem `patterns/variant-naming.md`: id `<família>-<variante>` kebab-case, rótulo em inglês Title Case sem parênteses, grupo do vocabulário fechado (`Start here`/`Default`/`Variants`/`Parts`/`Reference`/`Legacy`), situação via `status`, link sempre por `variantHref()`. |
+
+
+---
+
+## 2. Setup do projeto
+
+### 2.1 Dependência
+
+```bash
+npm i forlogic-core
+```
+
+### 2.2 `src/main.tsx` / `App.tsx`
+
+```tsx
+import { CoreProviders } from 'forlogic-core';
+import pt from './locales/pt-BR.json';
+import './index.css';
+
+<CoreProviders
+  backend="supabase"        // ou "dotnet" quando não há Supabase
+  appTranslations={{ 'pt-BR': pt }}
+>
+  <BrowserRouter>{/* rotas */}</BrowserRouter>
+</CoreProviders>
+```
+
+`CoreProviders` já monta: QueryClient, i18n + LanguageBootstrap, tema/essência,
+Tooltip, Toaster, Auth, Navigation, Module, PageMetadata e ModalState.
+**Não** duplicar nenhum desses providers no app.
+
+### 2.3 `src/index.css`
+
+```css
+@import 'forlogic-core/index.css';
+@import 'forlogic-core/legacy.css'; /* só se o app expõe o switch de versão */
+```
+
+Overrides do projeto entram **depois** do import, sempre em HSL e como token.
+
+### 2.4 `tailwind.config.ts`
+
+```ts
+import { forlogicTailwindPreset, forlogicContentPaths } from 'forlogic-core/tailwind';
+
+export default {
+  presets: [forlogicTailwindPreset],
+  content: [...forlogicContentPaths, './src/**/*.{ts,tsx}'],
+};
+```
+
+### 2.5 `vite.config.ts`
+
+```ts
+import { createForlogicConfig } from 'forlogic-core/vite';
+export default createForlogicConfig({ /* opções do projeto */ });
+```
+
+Já aplica alias `@`, headers de segurança/CSP, `resolveSupabaseEnv()` e o plugin
+que externaliza `forlogic-core` nos subpaths (evita duplicar React Context).
+
+### 2.6 `.env` mínimo
+
+```
+VITE_APP_ENV="PROD"            # ou "DEV" — única fonte de verdade de ambiente
+SUPABASE_URL=...
+SUPABASE_PUBLISHABLE_KEY=...
+VITE_SUPABASE_PK_OVERRIDE=...
+```
+
+---
+
+## 3. Layout obrigatório
+
+```tsx
+<AppLayout>            {/* h-screen overflow-hidden */}
+  <AppHeader />        {/* fixo; expõe --app-header-height */}
+  <AppSidebar />       {/* estado persistido por usuário */}
+  <BodyContent>        {/* flex-1 min-h-0 overflow-y-auto */}
+    {/* conteúdo da página */}
+  </BodyContent>
+</AppLayout>
+```
+
+- Título/subtítulo/breadcrumb **sempre** via `usePageMetadata()` — nunca `<h1>` solto na página.
+- `BodyContent` usa `overflow-visible` internamente para permitir popovers.
+- Rotas multi-tenant: `/:alias/<modulo>/...` é a única fonte de verdade de tenant.
+
+---
+
+## 4. Formulários e inputs
+
+- Base: `BaseForm` com config declarativa (`fields`, `sections`, `columns`).
+- Campos: `Input`, `Textarea`, `NumberInput`, `Combobox` (aliases `SelectSearch`,
+  `MultiSelect`, `EntitySelect`), `ComboTree` (`TreeSelect`), `DatePicker`,
+  `TimePicker`, `Switch`, `Checkbox`, `RadioGroup`, `IconPicker`, `SingleFileUpload`.
+- Contrato de borda: neutra `border-border`, hover `--control-surface-hover`,
+  foco `ring-[--control-ring]`. Raio base `rounded-lg` (8px).
+- Densidade: fonte base 13px (**Roobert Pro**), `px-3 py-2` em controles, `gap-2` entre elementos.
+- Tipografia: `Roobert Pro` (sans, empacotada na lib via `@font-face` em `forlogic-core/index.css`) e `Roboto Mono` (mono). Nunca declarar `font-family` fixo em componentes — usar `font-sans` / `font-mono` ou `var(--font-sans)`. Pesos: 400, 400 itálico e 700 (500 = Regular, 600+ = Bold).
+- Validação com `zod` + schemas de `forlogic-core/validation`.
+
+---
+
+## 5. Tabelas e CRUD
+
+- Página CRUD completa: `createCrudPage({ ... })` (memoizar config — obrigatório).
+- Tabela: `CrudTable` / `CrudPrimitiveTable` (alias `DataTable`).
+- **Defaults ligados por padrão**: sort, resize de colunas, column manager,
+  drag-and-drop de colunas, paginação, filtro.
+- Cabeçalhos: **uma palavra** por coluna (`columnTitle`), sem wrap; conteúdo longo
+  usa `TruncatedCell` (`EllipsisText`) com tooltip.
+- Densidade: header `h-9`, células `py-2`, `vertical-align: middle`.
+- Ações de linha: `RowActions` (hover-to-reveal, pill sticky no scroll horizontal)
+  + `RowContextMenu` com os mesmos comandos.
+- Ações em massa: `SelectionToolbar`.
+- Exclusão permanente: `AlertDialog`; exclusão lógica: dialog de confirmação padrão.
+- Read-only: passar `readOnly` ao `CrudTable` (esconde `+ Novo`, menus e ações).
+
+---
+
+## 6. Dialogs
+
+```tsx
+<Dialog>
+  <DialogContent size="md">      {/* sm | md | lg | xl | full */}
+    <DialogHeader />
+    <DialogBody className="px-2 -mx-2">  {/* OBRIGATÓRIO antes do footer */}
+      ...
+    </DialogBody>
+    <DialogFooter />
+  </DialogContent>
+</Dialog>
+```
+
+- `DialogBody` é obrigatório (scroll interno + focus ring visível).
+- Variantes semânticas: `default`, `danger`, `warning`, `success`, `info`.
+- Wizard multi-step: stepper vertical.
+- Alterações não salvas: interceptar o fechamento do Radix programaticamente
+  (`closeBtnRef`), nunca confiar no fechamento nativo.
+
+---
+
+## 7. Feedback
+
+- Toasts: `toast()` do `forlogic-core` (fundo sólido, nunca translúcido).
+- Estados vazios: `EmptyState`. Carregamento: `Skeleton` (não spinner solto).
+- Erros de serviço: `ErrorService` centraliza a mensagem exibida.
+
+---
+
+## 8. Tema
+
+- Modos: light / dark (navy) + **essências** de marca (`ESSENCES`, `buildEssenceTheme`).
+- Estado persistido em `localStorage` (`forlogic-ds:theme` / `:essence`) e refletido em `<html>`.
+- Trocar via `applyThemeState` / `setEssence`; nunca escrever CSS var direto no app.
+- Versionamento do DS: `DsVersionProvider` + `DsVersionSwitch` de `forlogic-core/versioning`
+  (v2 padrão; v1 apenas via `forlogic-core/legacy`).
+
+---
+
+## 9. Checklist antes de abrir PR no app consumidor
+
+- [ ] Nenhum import visual fora de `forlogic-core`.
+- [ ] Nenhuma cor/spacing hardcoded; só tokens.
+- [ ] `danger` em vez de `destructive`.
+- [ ] Ícones Lucide.
+- [ ] Um único scroll na tela.
+- [ ] Título/breadcrumb via `usePageMetadata`.
+- [ ] Toda query com `.schema()`.
+- [ ] Policies `TO authenticated`.
+- [ ] Textos via `t()` quando o módulo é multi-idioma.
+- [ ] Tabelas com header de uma palavra, resize e column manager ativos.
+
+---
+
+## 10. Como manter este knowledge atualizado
+
+Este arquivo é **gerado**: `docs/DS_KNOWLEDGE.md` = estas regras + seções
+dinâmicas extraídas do código (versão, subpaths, exports, tokens, padrões).
+
+```bash
+npm run ds:knowledge     # regenera docs/DS_KNOWLEDGE.md
+```
+
+- Roda automaticamente em `npm run build:lib` (antes do build da lib).
+- Alterou regra/padrão? Edite **este** `RULES.md` e regenere.
+- Adicionou/removeu componente, token, subpath ou padrão? Só regenerar — o
+  conteúdo dinâmico se atualiza sozinho.
+- No projeto consumidor: substitua o Workspace Knowledge pelo conteúdo novo de
+  `docs/DS_KNOWLEDGE.md`, ou referencie `@Admin docs/DS_KNOWLEDGE.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forlogic-core",
-  "version": "3.0.10",
+  "version": "4.0.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
@@ -62,12 +62,30 @@
       "types": "./dist/validation/index.d.ts",
       "import": "./dist/validation/index.esm.js",
       "require": "./dist/validation/index.js"
-    }
+    },
+    "./legacy": {
+      "types": "./dist/legacy/index.d.ts",
+      "import": "./dist/legacy/index.esm.js",
+      "require": "./dist/legacy/index.js"
+    },
+    "./versioning": {
+      "types": "./dist/versioning/index.d.ts",
+      "import": "./dist/versioning/index.esm.js",
+      "require": "./dist/versioning/index.js"
+    },
+    "./legacy.css": "./dist/legacy/index.css",
+    "./knowledge": "./docs/DS_KNOWLEDGE.md",
+    "./knowledge/compact": "./docs/DS_KNOWLEDGE_COMPACT.md",
+    "./knowledge/rules": "./docs/design-system/knowledge/RULES.md"
   },
   "files": [
     "dist",
-    "docs",
-    ".note/memory"
+    "docs/DS_KNOWLEDGE.md",
+    "docs/DS_KNOWLEDGE_COMPACT.md",
+    "docs/design-system/knowledge",
+    "bin",
+    ".note/memory",
+    "README.md"
   ],
   "sideEffects": [
     "*.css"
@@ -76,14 +94,34 @@
     "dev": "vite",
     "build": "vite build",
     "build:dev": "vite build --mode development",
-    "build:lib": "npx tsx scripts/generate-ds-docs.ts & tsc -p tsconfig.lib.json && rollup -c",
+    "build:lib": "npx tsx scripts/generate-ds-docs.ts & npx tsx scripts/generate-ds-knowledge.ts && tsc -p tsconfig.lib.json && rollup -c && npm run build:assets",
+    "build:assets": "node -e \"const fs=require('fs');fs.mkdirSync('dist/assets/fonts',{recursive:true});for(const f of fs.readdirSync('lib/assets/fonts'))fs.copyFileSync('lib/assets/fonts/'+f,'dist/assets/fonts/'+f);console.log('fonts copied to dist/assets/fonts')\"",
     "lint": "eslint .",
     "docs:check": "tsx scripts/check-docs.ts",
     "docs:check-all": "tsx scripts/check-docs.ts --all",
     "docs:fix": "tsx scripts/auto-doc.ts",
     "docs:fix-all": "tsx scripts/auto-doc.ts --all",
     "check:rls": "tsx scripts/check-rls.ts",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "ds:inventory": "tsx scripts/ds-inventory.ts",
+    "ds:diff": "tsx scripts/ds-inventory-diff.ts docs/design-system/inventory/baseline.json docs/design-system/inventory/inventory.json",
+    "ds:baseline": "npm run ds:inventory && cp docs/design-system/inventory/inventory.json docs/design-system/inventory/baseline.json",
+    "ds:check": "tsx scripts/check-ds-inventory.ts && tsx scripts/check-ds-quality.ts && tsx scripts/check-button-tokens.ts && tsx scripts/check-button-contrast.ts",
+    "ds:contrast": "tsx scripts/check-contrast.ts",
+    "ds:buttons": "tsx scripts/check-button-tokens.ts",
+    "ds:buttons:contrast": "tsx scripts/check-button-contrast.ts",
+    "ds:buttons:a11y": "tsx scripts/check-button-a11y.ts",
+    "ds:visual:buttons": "python3 scripts/visual/buttons-themes.py",
+    "ds:buttons:check": "npm run ds:buttons && npm run ds:buttons:contrast && npm run ds:buttons:a11y",
+    "ds:visual:dialog-buttons": "python3 scripts/visual/dialog-buttons.py",
+    "ds:visual:nav-parity": "python3 scripts/visual/nav-primary-parity.py",
+    "ds:codemod": "tsx scripts/codemod-ds-imports.ts",
+    "ds:codemod:dry": "tsx scripts/codemod-ds-imports.ts --dry",
+    "ds:row-actions": "tsx scripts/check-row-actions.ts",
+    "ds:visual:table-actions": "python3 scripts/visual/table-actions-scroll.py",
+    "ds:knowledge": "tsx scripts/generate-ds-knowledge.ts",
+    "ds:knowledge:sync": "node bin/ds-knowledge.js",
+    "check:ds-surfaces": "tsx scripts/check-ds-surfaces.ts"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
@@ -91,6 +129,7 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@hookform/resolvers": "^3.10.0",
     "@microsoft/clarity": "^1.0.2",
+    "@phosphor-icons/react": "^2.1.10",
     "@radix-ui/react-accordion": "^1.2.11",
     "@radix-ui/react-alert-dialog": "^1.1.14",
     "@radix-ui/react-avatar": "^1.1.10",
@@ -169,6 +208,9 @@
     "@rollup/plugin-url": "^8.0.2",
     "@svgr/rollup": "^8.1.0",
     "@tailwindcss/typography": "^0.5.16",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.5",
     "@types/file-saver": "^2.0.7",
     "@types/node": "^22.16.5",
     "@types/react": "^19.2.18",
@@ -181,6 +223,7 @@
     "eslint-plugin-react-refresh": "^0.4.20",
     "exceljs": "^4.4.0",
     "globals": "^15.15.0",
+    "jsdom": "^30.0.1",
     "lovable-tagger": "^1.1.9",
     "postcss": "^8.5.18",
     "react": "^19.2.8",
@@ -194,10 +237,14 @@
     "tsx": "^4.20.6",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.38.0",
-    "vite": "^7.3.0"
+    "vite": "^7.3.0",
+    "vitest": "^3.2.4"
   },
   "allowScripts": {
     "@swc/core@1.15.18": true,
     "esbuild@0.28.1": true
+  },
+  "bin": {
+    "forlogic-ds-knowledge": "bin/ds-knowledge.js"
   }
 }

package/.note/memory/features/import/attachment-idempotency-registry.md

@@ -1,8 +0,0 @@
-# Memory: features/import/attachment-idempotency-registry
-Updated: now
-
-## REMOVIDO
-
-O controle de idempotência via tabela `common.imports_file_registry` foi removido para simplificar o fluxo de importação de anexos. Agora todo arquivo válido (>0 bytes) é enviado diretamente ao Azure Blob Storage sem verificar se já existe no registry. As funções `lookupExistingFiles`, `registerUploadedFiles` e o campo `newFiles` do `UploadResult` foram removidos de `attachmentUploadService.ts`.
-
-A tabela `common.imports_file_registry` no Supabase pode ser removida manualmente se desejado — a aplicação não a consulta mais.

package/.note/memory/features/import/attachment-strategy.md

@@ -1,30 +0,0 @@
-# Memory: features/import/attachment-strategy
-Updated: now
-
-O sistema de anexos usa upload direto ao Azure Blob Storage (sem staging). O .zip contém pastas nomeadas pelo código do registro (ex: `OC-001/foto.pdf`). Cada arquivo recebe um `id_file_revision` de 8 caracteres alfanuméricos (`crypto.randomUUID().slice(0,8)`) gerado no front-end. O arquivo é enviado ao container `un{id_company}` com nome `{id_file_revision}.{ext}`. Esse mesmo ID é incluído no CSV como coluna `id_file_revision` para que a API grave no banco com a mesma referência.
-
-## Idempotência via `common.imports_file_registry`
-
-Tabela Supabase com PK `CHAR(8)` (o próprio `id_file_revision`) e constraint `UNIQUE(alias, code, file_name)`:
-- Se `(alias, code, file_name)` já existe com **mesmo tamanho** → reutiliza `id_file_revision` e `blob_url`, **não faz upload**
-- Se existe com **tamanho diferente** → erro de conflito
-- Se não existe → gera novo ID, faz upload, registra no registry **somente após sucesso da API**
-- Arquivos com 0 bytes são rejeitados imediatamente
-
-## Fluxo de consistência
-
-1. Upload para Azure (novos arquivos)
-2. Envio do CSV para API staging
-3. **Se API sucesso** → `registerUploadedFiles()` grava no registry
-4. **Se API falhar** → registry NÃO é gravado, próxima tentativa refaz upload
-
-## Templates de anexo (attachment-only)
-
-Quando `import_target === 'attachments'` ou todos os campos ativos são `file`/`file_metadata`, o sistema detecta automaticamente. Nesse modo:
-- O .zip **não precisa conter xlsx** — apenas pastas com arquivos
-- O código é extraído do **diretório pai imediato** do arquivo
-- As linhas do CSV são geradas automaticamente a partir dos metadados
-- Função `executeAttachmentOnlyImport` orquestra o fluxo completo
-- `buildRowsFromAttachments` gera as linhas
-- `extractZipAttachmentsOnly` extrai sem exigir xlsx
-- `isAttachmentOnlyTemplate` detecta o tipo

package/.note/memory/patterns/admin-i18n-policy.md

@@ -1,20 +0,0 @@
-# Política de Idioma — Admin, Design System e Lib
-
-## Decisão
-
-| Camada | Idioma | i18n (useTranslation) |
-|--------|--------|-----------------------|
-| **Projeto Admin (`src/`)** | Português (Brasil) — hardcoded | ❌ Não usa |
-| **Design System (`src/design-system/`)** | Português (Brasil) — hardcoded | ❌ Não usa |
-| **Lib (`lib/`)** | Multi-idioma (pt-BR, en-US, es-ES) | ✅ Usa `t()` + JSONs |
-
-## Regras
-
-1. **Nenhum arquivo em `src/`** deve importar `useTranslation` ou usar `t()` — todos os textos são strings fixas em português.
-2. **A documentação interativa do Design System** (páginas `*Doc.tsx`, sidebar, home) é escrita diretamente em português, sem chaves de tradução.
-3. **A lib (`lib/`)** mantém o sistema completo de i18n com namespaces, JSONs por idioma e integração com Tolgee, pois é consumida por projetos que precisam de múltiplos idiomas.
-4. **Arquivos de tradução da lib** (`lib/i18n/locales/`) contêm apenas chaves usadas pelos componentes internos da lib.
-
-## Contexto
-
-O Admin é um painel interno da Forlogic usado exclusivamente em português. Manter i18n no Admin adiciona complexidade sem benefício. A lib, por outro lado, é distribuída para projetos consumidores que operam em múltiplos idiomas.

package/.note/memory/patterns/alias-url-resolution.md

@@ -1,69 +0,0 @@
-# Alias via URL — Resolução de Unidade por Rota
-
-## Padrão
-
-O alias da unidade ativa deve **sempre** estar presente na URL como primeiro segmento de rota (`/:alias/...`). A **URL é a fonte única de verdade** para o alias ativo.
-
-## Arquitetura (URL como Source of Truth)
-
-```
-Header/Seletor → navigate(/{novoAlias}/...) → URL muda → AliasRouteGuard → switchUnit()
-```
-
-- **Header/UI**: Apenas navega (muda a URL). Nunca chama `switchUnit` diretamente.
-- **AliasRouteGuard**: Detecta que `urlAlias !== activeAlias` e chama `switchUnit()` para sincronizar a sessão.
-- **Resultado**: Um único writer (guard) controla a sessão, eliminando race conditions.
-
-## Componentes
-
-### `useAliasFromUrl(options?)`
-Hook que extrai o alias do param de rota e valida contra `companies` do `useAuth()`.
-
-Retorna: `{ urlAlias, isAliasMismatch, isValidAlias, isMissing, matchedCompany }`
-
-### `AliasRouteGuard`
-Wrapper de rota com **auto-detect de modo**:
-
-- **Modo URL** (`:alias` presente na rota): comportamento padrão com 1 effect de decisão
-- **Modo Legado** (sem `:alias` na rota): passthrough transparente, sem redirects
-
-| Cenário (Modo URL) | Ação |
-|---------|------|
-| Alias ausente na URL | Redireciona para `/{aliasAtivo}/{path}` |
-| Alias inválido | Redireciona para `/{aliasAtivo}/{path}` |
-| Alias válido e diferente do ativo | Chama `switchUnit()` |
-| Alias correto | Renderiza children |
-
-Proteção de concorrência: `switchingRef` evita chamadas duplicadas no mesmo ciclo.
-
-### `AppHeader` (mudança de unidade)
-
-O header usa `navigate()` para trocar o segmento de alias na URL:
-
-```tsx
-const handleUnitChangeNavigate = (company) => {
-  const segments = pathname.split('/');
-  const aliasIndex = segments.indexOf(alias);
-  segments[aliasIndex] = company.alias;
-  navigate(segments.join('/') + search + hash);
-};
-
-<UserInfo onUnitChange={handleUnitChangeNavigate} />
-```
-
-## Uso nos Consumidores
-
-```tsx
-<Route element={<ProtectedRoute><AliasRouteGuard><Outlet /></AliasRouteGuard></ProtectedRoute>}>
-  <Route path="/:alias/documents" element={<DocumentsPage />} />
-  <Route path="/:alias/documents/:id" element={<DocumentDetailPage />} />
-</Route>
-```
-
-## Regras
-- Guard só age após `isLoading=false && isAuthenticated=true`
-- Usa `replace: true` para evitar poluir o histórico
-- Se `switchUnit` falha, mantém alias atual (sem loop)
-- `switchUnit` já faz `queryClient.clear()` — cache é limpo automaticamente
-- Navegação inter-módulos já usa `{alias}` nas URLs (`modulesData.ts`)
-- **Header/seletor NUNCA chama switchUnit diretamente** — apenas navega

package/.note/memory/patterns/doc-sync-rule.md

@@ -1,35 +0,0 @@
-# Regra: Sincronização Automática de Documentação
-
-## Gatilho
-
-Sempre que modificar qualquer arquivo em `lib/`, verificar se existe documentação correspondente em `src/design-system/docs/`.
-
-**Esta regra é obrigatória e deve ser aplicada em toda alteração de componente, sem exceção.**
-
-## Ações obrigatórias
-
-### 1. Componente/hook existente com doc existente
-- Atualizar props, exemplos, hierarquias e descrições no `*Doc.tsx` correspondente para refletir a mudança
-- Atualizar previews interativos para que reflitam o comportamento atual do componente
-
-### 2. Componente/hook novo sem doc
-- Criar `*Doc.tsx` usando `ComponentDocTemplate` (com prop `usage` obrigatória)
-- Registrar no `src/design-system/config/docRegistry.ts` (lazy import)
-- Registrar no `src/design-system/config/sections.ts` (sidebar + breadcrumb)
-
-### 3. Mudanças arquiteturais
-- Atualizar `docs/KNOWLEDGE.md` se afetar regras, mapa de módulos ou convenções
-- Atualizar `.note/memory/` se afetar padrões documentados
-
-## Mapeamento de referência
-
-```
-lib/components/ui/<comp>.tsx      → src/design-system/docs/components/<Comp>Doc.tsx
-lib/crud/components/<comp>.tsx    → src/design-system/docs/components/crud/<Comp>Doc.tsx
-lib/contexts/<Context>.tsx        → src/design-system/docs/ContextsDoc.tsx
-lib/hooks/<hook>.ts               → src/design-system/docs/HooksDoc.tsx
-lib/services/<Service>.ts         → src/design-system/docs/ServicesDoc.tsx
-lib/components/layout/<comp>.tsx  → src/design-system/docs/components/layout/<Comp>Doc.tsx
-```
-
-Consultar `.note/memory/patterns/components-registry.md` para componentes agrupados sob uma única doc.

package/.note/memory/patterns/documentation-standard.md

@@ -1,17 +0,0 @@
-# Design System Documentation Standard
-
-## Fonte de verdade
-
-Os arquivos `*Doc.tsx` em `src/design-system/docs/` são a fonte de verdade para documentação de componentes. Eles alimentam a rota `/ds` no app.
-
-## Regras para *Doc.tsx
-
-- Devem usar `ComponentDocTemplate` com a prop `usage` obrigatória (snippet de código)
-- Seções críticas como ModuleAccess e Audit Log devem incluir padrões SQL e configurações
-- Exemplos visuais interativos são obrigatórios para componentes complexos
-
-## Acesso à documentação
-
-- **Rota `/ds`**: Design system interativo no app
-- **Cross-project**: IA lê `*Doc.tsx` diretamente do código-fonte do projeto **Admin** (forlogic-core)
-- **Não há mais geração automática** de `DESIGN_SYSTEM.md` — foi removido em favor de leitura direta

package/.note/memory/patterns/dynamic-supabase-config.md

@@ -1,4 +0,0 @@
-# Memory: patterns/dynamic-supabase-config
-Updated: 2026-05-25
-
-O `vite.config.ts` chama `resolveSupabaseEnv(mode)` (de `forlogic-core/vite`), que lê tanto `VITE_SUPABASE_*` quanto `SUPABASE_*` (formato novo Lovable Cloud), prioriza `VITE_*` e injeta valores consolidados via `define`: `import.meta.env.VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY`, `VITE_SUPABASE_PROJECT_ID`, `VITE_SUPABASE_PK_OVERRIDE`. O `.env` precisa apenas de UMA versão (`SUPABASE_URL` + `SUPABASE_PUBLISHABLE_KEY`). `VITE_SUPABASE_PK_OVERRIDE` continua obrigatório por causa do bug do Lovable sobrescrever a publishable key com a legacy JWT. `projectId` é derivado da URL quando ausente.

package/.note/memory/patterns/environment-detection-logic.md

@@ -1,41 +0,0 @@
-# Memory: patterns/environment-detection-logic
-Updated: 2026-05-25
-
-O sistema separa duas preocupações independentes de ambiente:
-
-## 1. Método de autenticação (`shouldUseDevTokens()` / `isLovablePreview()`)
-Detecta se o app roda em contexto de desenvolvimento (preview Lovable via iframe, `*.lovable.dev`, localhost ou `import.meta.env.DEV`). Quando true, usa a edge function `dev-tokens` do Supabase conectado para autenticar. Quando false (app publicado), usa OAuth padrão do Qualiex.
-
-## 2. Qual API usar (`getEnvironmentConfig()` / `isDevEnv()`)
-Fonte de verdade **única e explícita**: env var `VITE_APP_ENV`.
-
-| `VITE_APP_ENV`                  | Resultado             |
-|---------------------------------|-----------------------|
-| `"PROD"`                        | PROD (API/OAuth prod) |
-| `"DEV"`                         | DEV (API/OAuth dev)   |
-| ausente / qualquer outro valor  | **PROD (failsafe)**   |
-
-Não há fallback derivado do Supabase. Apps que querem apontar para dev precisam declarar `VITE_APP_ENV="DEV"` no `.env`. Apps prod simplesmente omitem (ou setam `"PROD"`).
-
-## Tabela de regras
-
-| Cenário                         | API  | Auth       |
-|---------------------------------|------|------------|
-| Preview + `VITE_APP_ENV=PROD`   | Prod | dev-tokens |
-| Preview + `VITE_APP_ENV=DEV`    | Dev  | dev-tokens |
-| Publicado + `VITE_APP_ENV=PROD` | Prod | OAuth      |
-| Publicado + `VITE_APP_ENV=DEV`  | Dev  | OAuth      |
-
-## Guard de troca de projeto (`TokenManager.checkProjectMismatch()`)
-Independente de `VITE_APP_ENV`. Ao inicializar (`AuthService.initialize()`), compara `import.meta.env.VITE_SUPABASE_PROJECT_ID` (consolidado por `resolveSupabaseEnv()` no `vite.config.ts`) com o valor armazenado em `localStorage('supabase_project_id')`. Se diferente, limpa tokens stale antes de qualquer chamada a `validate-token`. Sem efeito em apps `backend="dotnet"`.
-
-## Funções (lib/config/index.ts)
-- `isLovablePreview()` — detecta contexto de preview/localhost
-- `shouldUseDevTokens()` — wrapper semântico sobre `isLovablePreview()` (apenas modo Supabase)
-- `isDevEnvironment` — alias deprecated, mantido para compatibilidade
-- `getAppEnv()` — retorna `'PROD' | 'DEV'` lendo `VITE_APP_ENV` (default `'PROD'`)
-- `getEnvironmentConfig()` — retorna config PROD ou DEV baseado em `getAppEnv()`
-- `isDevEnv()` — true se `getAppEnv() === 'DEV'`
-
-## Funções (lib/auth/services/TokenManager.ts)
-- `checkProjectMismatch()` — detecta troca de projeto Supabase e limpa tokens stale

package/.note/memory/patterns/i18n-architecture.md

@@ -1,3 +0,0 @@
-# i18n Architecture
-
-A internacionalização utiliza namespaces 'core' (lib) e 'app' (consumidor). Traduções do consumidor são modularizadas em arquivos JSON por feature e mescladas via `mergeTranslationFiles`. Usa apenas i18next + JSONs estáticos (sem serviço externo de tradução). É mandatório o uso do hook `useTranslation` da biblioteca, garantindo fallback e suporte a flags de depuração. Os arquivos de tradução da biblioteca (`lib/i18n/locales/`) são restritos exclusivamente a chaves utilizadas por seus componentes internos; chaves órfãs ou termos de domínio de negócio devem ser geridos e traduzidos nos projetos consumidores no namespace 'app'.

package/.note/memory/security/lib-hardening-roadmap.md

@@ -1,45 +0,0 @@
----
-name: Lib hardening roadmap
-description: Roadmap de hardening do forlogic-core dividido em blocos por impacto (zero-impact → opt-in → breaking)
-type: feature
----
-
-Plano completo em `.lovable/plan.md`. Status:
-
-**Bloco 1 (patch, zero impact — IMPLEMENTADO)**
-- Headers de dev reforçados: COOP, CORP, bloqueio de TRACE/CONNECT, Vary sempre.
-- SupabaseSingleton bloqueia `apikey` em query string.
-- `errorService` usa `sanitizeErrorMessage` + `generateId('short')`.
-- `lib/utils/generateId.ts`, `lib/utils/sanitizeError.ts`.
-- `lib/validation/schemas.ts` reexportado pelo barrel.
-- `scripts/check-rls.ts` + `npm run check:rls`.
-
-**Bloco 2 (minor, opt-in — IMPLEMENTADO)**
-- Subpath `forlogic-core/edge`: requireUserJWT, requireOwnership, safeJsonParse, jsonError, rateLimit, withCors, corsPreflight, stripTechHeaders, HttpError. Standalone (sem deps de React/Supabase SDK).
-- Subpath `forlogic-core/storage`: detectMimeFromMagicBytes, validateMagicBytes, sanitizeAndRandomizeFilename, getSignedUrl, RECOMMENDED_PRIVATE_BUCKETS, SAFE_IMAGE_MIME, SAFE_DOCUMENT_MIME.
-- Subpath `forlogic-core/validation`: schemas zod (também no barrel).
-- `lib/templates/migrations/`: 01-user-owned-table.sql, 02-user-roles.sql, README.
-- `CoreProviders` ganha prop opcional `securityMode?: 'legacy' | 'strict'` (default `legacy`) + helper `getSecurityMode()`.
-- `package.json#exports` e `rollup.config.js` configurados para os 3 novos subpaths (standaloneBuilds).
-
-**Bloco 3 (major v2.0.0 — breaking, próxima fase)**
-- JWT fora de localStorage.
-- `apikey` fora da URL no Realtime.
-- CORS default restritivo (sem `*.lovable.app`).
-- SameSite=Strict em cookies.
-- Lint rule banindo `Date.now()` como ID.
-- `securityMode='strict'` vira default; flag removida em v3.
-
-## Uso pelos consumidores
-
-```ts
-// Edge Function (Deno)
-import { requireUserJWT, jsonError, rateLimit } from 'npm:forlogic-core/edge';
-
-// Browser
-import { validateMagicBytes, SAFE_IMAGE_MIME, sanitizeAndRandomizeFilename } from 'forlogic-core/storage';
-import { emailSchema, userIdSchema } from 'forlogic-core/validation';
-
-// App root
-<CoreProviders securityMode="strict">...</CoreProviders>
-```

package/.note/memory/security/react-router-dom-v7-migration.md

@@ -1,33 +0,0 @@
----
-name: react-router-dom v7 migration + peer dependency
-description: forlogic-core 2.5.0 bumpou react-router-dom 6→7 e moveu pra peerDependencies — consumidores precisam alinhar a própria versão antes de atualizar
-type: feature
----
-
-## O que mudou (forlogic-core 2.5.0)
-
-- `react-router-dom`: `6.30.1` → `7.18.1`.
-- Saiu de `dependencies` e virou `peerDependencies` — o app consumidor agora é responsável por instalar a versão compatível.
-
-## Por que isso quebra apps que não atualizarem
-
-`react-router-dom` era dependência normal mas já tratada como externa no build (`rollup.config.js#externalDeps`) — ou seja, o app sempre precisou fornecer a própria instância em runtime. O problema: sem ser peer, o npm não avisava sobre incompatibilidade de versão, só instalava as duas cópias silenciosamente. Um app ainda em v6 + lib pedindo v7 = duas instâncias de React Router no bundle = contexto de `<Router>` não bate entre os hooks da lib (`useNavigate`, `useLocation`, etc. usados em `lib/components/layout/*`, `lib/crud/*`, `lib/auth/*`) e o `<BrowserRouter>` do app.
-
-## Checklist pra IA/dev atualizando um app consumidor
-
-1. Checar `package.json` do app: `react-router-dom` precisa ser `^7.18.1` (ou compatível) **antes** de subir `forlogic-core` pra `>=2.5.0`.
-2. Se o app usa só API declarativa (`Routes`, `Route`, `Link`, `Navigate`, `Outlet`, `useNavigate`, `useLocation`, `useParams`, `useSearchParams`, `BrowserRouter`) — migração 6→7 tende a ser troca de versão sem mudança de código.
-3. Se o app usa **data router** (`createBrowserRouter`, loaders, actions, `<Form>`) — revisar changelog oficial do react-router v7, há mudanças de API nesse modo que a lib não usa e portanto não foi validado aqui.
-4. Rodar `npm ls react-router-dom` no app depois do install — se aparecer mais de uma versão resolvida (não deduped), o conflito não foi resolvido.
-
-## Risco aceito relacionado: GHSA-qwww-vcr4-c8h2 (high) — RESOLVIDO na 3.0.0
-
-react-router (core, 7.12.0–8.2.0) tem CVE alto de CSRF bypass em "RSC Mode". Fix é `react-router@8.3.0`, mas na época:
-- `react-router-dom` (pacote usado aqui) não tem release 8.x.
-- `react-router@8.3.0` exige React `>=19.2.7` — ver [[react19-migration-roadmap]].
-
-Foi aceito como risco porque não exploitável no padrão de uso desta lib (sem RSC, sem actions/loaders, sem SSR — só roteamento client-side declarativo).
-
-**Corrigido em 2026-08-01 (`forlogic-core@3.0.0`):** migração pra React 19 + `react-router@8.3.0` executada. `npm audit` = 0 vulnerabilidades. Detalhes e checklist pro app consumidor em [[react19-migration-roadmap]].
-
-> **Este documento descreve a 2.5.0 e está superado a partir da 3.0.0.** O pacote `react-router-dom` não existe mais no v8 — quem for atualizar direto de `<2.5.0` pra `^3.0.0` deve seguir o checklist do [[react19-migration-roadmap]], não o daqui.