up-cc 0.3.3 → 0.4.1

package/references/blueprints/saas-users.md

@@ -0,0 +1,50 @@
+# Blueprint: SaaS Users & Permissions
+
+Aplicar quando: sistema tem login, multiplos usuarios, ou qualquer menção a "admin", "roles", "permissoes".
+Praticamente TODO sistema web com auth precisa deste blueprint.
+
+---
+
+## Autenticacao (AUTH)
+
+- AUTH-01: Login com email/senha
+- AUTH-02: Signup com verificacao de email
+- AUTH-03: Forgot password (enviar link de reset)
+- AUTH-04: Reset password (pagina com token)
+- AUTH-05: Alteracao de senha (logado, exige senha atual)
+- AUTH-06: Logout com limpeza de sessao
+- AUTH-07: Sessao persistente (refresh token / remember me)
+- AUTH-08: Redirect pos-login para pagina de origem
+- AUTH-09: Loading state durante verificacao de auth (nao piscar login)
+- AUTH-10: OAuth social (Google, GitHub) — se aplicavel ao dominio
+
+## Perfil de Usuario (PROFILE)
+
+- PROFILE-01: Pagina de perfil (nome, email, foto, contato)
+- PROFILE-02: Upload de foto de perfil (com crop/resize)
+- PROFILE-03: Edicao de dados pessoais
+- PROFILE-04: Visualizacao de plano/role atual
+- PROFILE-05: Historico de atividade do usuario
+
+## Roles e Permissoes (ROLE)
+
+- ROLE-01: Definir roles do sistema (ex: admin, gerente, atendente, cliente)
+- ROLE-02: Cada role tem permissoes especificas (CRUD por modulo)
+- ROLE-03: Tabela de permissoes: role × modulo × acao (ver, criar, editar, deletar)
+- ROLE-04: UI adapta baseado no role (menus, botoes, paginas visiveis)
+- ROLE-05: API valida permissoes (nao depender apenas do front)
+- ROLE-06: Role padrao para novos usuarios (configuravel)
+- ROLE-07: Super admin (acesso total, nao removivel)
+
+## Gestao de Usuarios (USRMGMT)
+
+- USRMGMT-01: Listar usuarios (com busca, filtro por role, paginacao)
+- USRMGMT-02: Criar usuario (nome, email, role, senha temporaria ou convite)
+- USRMGMT-03: Editar usuario (nome, email, role)
+- USRMGMT-04: Desativar/reativar usuario (soft delete, nao hard delete)
+- USRMGMT-05: Reset de senha por admin (gerar link de reset)
+- USRMGMT-06: Alterar role de usuario
+- USRMGMT-07: Convite por email (link de signup com role pre-definido)
+- USRMGMT-08: Indicador de status (ativo, inativo, pendente convite)
+- USRMGMT-09: Acessivel apenas para admin
+- USRMGMT-10: Log de alteracoes (quem mudou o que)

package/references/blueprints/settings.md

@@ -0,0 +1,31 @@
+# Blueprint: Settings & Configuration
+
+Aplicar quando: sistema tem configuracoes ajustaveis pelo usuario ou admin.
+Praticamente TODO sistema SaaS precisa deste blueprint.
+
+---
+
+## Perfil & Conta (ACCT)
+
+- ACCT-01: Pagina de configuracoes com sidebar/tabs por secao
+- ACCT-02: Secao "Perfil" (nome, foto, bio, contato)
+- ACCT-03: Secao "Seguranca" (alterar senha, sessoes ativas)
+- ACCT-04: Secao "Notificacoes" (preferencias de canal e tipo)
+- ACCT-05: Secao "Aparencia" (tema claro/escuro, idioma)
+- ACCT-06: Secao "Dados" (export dos meus dados, deletar conta)
+- ACCT-07: Save com feedback (toast de sucesso)
+
+## Configuracao do Negocio — Admin Only (BIZ)
+
+- BIZ-01: Dados do negocio (nome, logo, endereco, CNPJ, contato)
+- BIZ-02: Horario de funcionamento
+- BIZ-03: Configuracao de moeda e locale
+- BIZ-04: Configuracao de email (remetente, templates)
+- BIZ-05: Integrações ativas (toggle on/off, chaves de API)
+- BIZ-06: Plano atual e billing info (se SaaS multi-tenant)
+
+## Customizacao Visual — Admin Only (THEME)
+
+- THEME-01: Logo upload
+- THEME-02: Cores primarias (se white-label)
+- THEME-03: Favicon customizado

package/references/engineering-principles.md

@@ -0,0 +1,205 @@
+# Engineering Principles
+
+Principios que governam TODA decisao de implementacao no UP.
+Carregado por todos os agentes executores (up-executor, up-frontend-specialist, up-backend-specialist, up-database-specialist).
+
+Estes principios existem porque IAs tendem a escolher o caminho mais facil, nao o melhor. Cada principio combate um vicio especifico.
+
+---
+
+## Principio 1: Implementacao real, nao simulacao
+
+NUNCA entregue codigo que PARECE funcionar mas nao funciona de verdade.
+
+**Violacoes comuns (PROIBIDO):**
+
+```typescript
+// ❌ Handler vazio
+onClick={() => {}}
+
+// ❌ Componente placeholder
+function UserList() {
+  return <div>User List</div>
+}
+
+// ❌ API que retorna estatico
+export async function GET() {
+  return Response.json({ ok: true })
+}
+
+// ❌ Form que nao envia
+onSubmit={(e) => e.preventDefault()}
+
+// ❌ Estado que nunca popula
+const [users, setUsers] = useState([])
+// ... nunca chama setUsers com dados reais
+
+// ❌ Import decorativo
+import { analytics } from './analytics'
+// ... nunca chama analytics
+
+// ❌ Fetch sem uso
+const data = await fetch('/api/users')
+// ... nunca usa data
+```
+
+**O que fazer quando nao pode implementar agora:**
+
+Se falta API externa, credencial ou dependencia:
+1. NAO finja que funciona
+2. Declare explicitamente no SUMMARY como "nao implementado — motivo: X"
+3. Deixe o codigo com erro CLARO, nao silencio enganoso:
+
+```typescript
+// ✅ Correto: explicitamente nao implementado
+function exportCSV() {
+  throw new Error('Export CSV nao implementado — aguardando endpoint /api/export')
+}
+```
+
+---
+
+## Principio 2: A implementacao correta, nao a mais rapida
+
+Quando existem duas abordagens — a rapida que funciona superficialmente e a correta que trata todos os cenarios — SEMPRE escolha a correta.
+
+| Situacao | ❌ Atalho | ✅ Correto |
+|----------|----------|-----------|
+| Validar email | `.includes('@')` | Regex ou library (zod, yup) |
+| Tipagem | `any` para compilar | Interface/type definido |
+| Catch erro | `catch(e) {}` vazio | `catch(e) { toast.error(e.message) }` |
+| Query SQL | `WHERE id = ${id}` | `WHERE id = $1`, [id] |
+| Acesso array | `data[0]` direto | `data?.length ? data[0] : null` |
+| Checar null | `if (data)` generico | `if (data !== null && data !== undefined)` |
+| Comparacao | `==` | `===` |
+| Copiar objeto | `Object.assign` raso | `structuredClone` ou spread profundo |
+| Lidar com datas | String manipulation | Library (date-fns, dayjs) |
+| Gerar ID | `Math.random()` | `crypto.randomUUID()` |
+
+**Teste mental:** "Se um dev senior revisasse esse codigo, ele aceitaria ou pediria mudanca?"
+Se pediria mudanca → faca a versao correta agora.
+
+---
+
+## Principio 3: Conectado de ponta a ponta
+
+Codigo NAO esta "pronto" ate que esteja WIRED — conectado e funcionando do ponto de vista do usuario final.
+
+**Checklist de wiring:**
+
+| Criado | Conectado a | Verificacao |
+|--------|-------------|-------------|
+| Componente | Layout/pagina + rota navegavel | Acessar URL, componente renderiza |
+| API endpoint | Frontend chama + response tratado | curl funciona + UI mostra dados |
+| Schema/migration | Migration rodada + queries usando | Dados persistem e retornam |
+| Validacao | Aplicada no form + feedback visivel | Submeter invalido, ver mensagem |
+| Estado (store) | Mutations conectadas + UI reflete | Mutar, UI atualiza |
+| Auth guard | Rota protegida + redirect se nao logado | Acessar sem login, redireciona |
+| Event handler | Botao/elemento + acao executa | Clicar, algo acontece |
+
+**"O arquivo existe" ≠ "funciona".**
+**"Funciona" = usuario final consegue usar no browser.**
+
+Apos CADA tarefa, verificar wiring:
+- Backend: `curl` o endpoint, verificar response
+- Frontend: navegar a pagina, verificar que renderiza e responde
+- Integracao: frontend chama backend, dados fluem
+
+---
+
+## Principio 4: Consistencia sobre criatividade
+
+NAO invente patterns novos quando o projeto ja tem um pattern estabelecido.
+
+**Antes de implementar qualquer coisa:**
+
+```bash
+# 1. Buscar implementacao similar no codebase
+grep -r "similar_pattern" src/ --include="*.ts" --include="*.tsx"
+
+# 2. Se existe: SEGUIR o mesmo pattern
+# 3. Se nao existe: estabelecer pattern e ser consistente daqui pra frente
+```
+
+**Exemplos:**
+
+| Projeto usa | ❌ NAO faca | ✅ Faca |
+|-------------|-----------|--------|
+| React Query | `fetch` manual com useState | `useQuery`/`useMutation` |
+| Componente Button | `<button className="...">` raw | `<Button variant="primary">` |
+| Tailwind | `style={{ color: 'blue' }}` | `className="text-blue-500"` |
+| Zod validation | `if (!email.includes('@'))` manual | `z.string().email()` |
+| Toast via Sonner | `alert('Sucesso')` | `toast.success('Sucesso')` |
+| tRPC | REST fetch manual | `trpc.resource.query()` |
+| Supabase client | `fetch('/api/...')` wrapper | `supabase.from('...').select()` |
+
+**Regra geral:** Se o codebase ja resolveu esse problema, use a mesma solucao.
+
+---
+
+## Principio 5: Dados reais desde o primeiro momento
+
+NAO use mock data como solucao permanente.
+
+**Ordem de preferencia:**
+1. Banco de dados real com seed data → IDEAL
+2. API real com dados de teste → BOM
+3. Mock temporario removido antes do commit → ACEITAVEL
+4. Hardcoded no componente como solucao final → PROIBIDO
+
+**Se o banco existe:** Conecte desde o primeiro componente.
+**Se precisa seed:** Crie migration/seed file, NAO hardcode:
+
+```typescript
+// ❌ PROIBIDO: dados fake no componente
+const transactions = [
+  { id: 1, amount: 100, description: 'Test' },
+  { id: 2, amount: 200, description: 'Test 2' },
+]
+
+// ✅ CORRETO: buscar do banco
+const { data: transactions } = useQuery({
+  queryKey: ['transactions'],
+  queryFn: () => supabase.from('transactions').select('*')
+})
+
+// ✅ E criar seed separado:
+// supabase/seed.sql ou prisma/seed.ts
+```
+
+**Mock aceitavel APENAS em:**
+- Testes automatizados (vi.mock, jest.mock)
+- Desenvolvimento temporario (removido antes do commit)
+- API externa indisponivel (documentar explicitamente)
+
+---
+
+## Principio 6: Cada decisao tem custo futuro
+
+Antes de escolher a abordagem facil, pergunte: **"Se o projeto crescer 10x, essa decisao vai causar retrabalho?"**
+
+| Atalho agora | Custo futuro |
+|-------------|-------------|
+| Tudo num arquivo so | Refatorar quando ficar ilegivel |
+| Sem tipagem | Bugs silenciosos, refatorar depois |
+| Sem validacao | Dados lixo no banco, limpar depois |
+| Sem pagination | App trava com 10k items |
+| Sem error handling | Crash em producao, debug cego |
+| Sem indices no banco | Queries lentas com volume |
+| Sem loading states | UX ruim, usuario acha que travou |
+| CSS inline/hardcoded | Inconsistencia visual, refatorar tema |
+| Sem env vars | Credenciais expostas, security breach |
+| Sem testes | Medo de mudar codigo, regressoes |
+
+**Se a resposta for "sim, vai causar retrabalho":** faca certo agora. O custo de fazer certo e linear. O custo de refatorar depois e exponencial.
+
+---
+
+## Como aplicar durante execucao
+
+1. **Antes de cada tarefa:** Reler os principios mentalmente
+2. **Durante implementacao:** A cada decisao, checar se viola algum principio
+3. **Antes de commitar:** Self-review rapido contra os 6 principios
+4. **No SUMMARY:** Documentar decisoes onde o principio influenciou a escolha
+
+**Se violar um principio para cumprir deadline:** Documentar como debito tecnico no SUMMARY, NAO fingir que esta correto.

package/references/production-requirements.md

@@ -0,0 +1,106 @@
+# Production Requirements Reference
+
+Checklist de requisitos que TODO sistema pronto para producao deve ter.
+O up-system-designer e up-arquiteto usam esta referencia para injetar requisitos automaticamente.
+
+Cada item e um requisito com ID sugerido. O arquiteto ajusta IDs para nao colidir com requisitos explicitos do usuario.
+
+---
+
+## UI States (UIST)
+
+- UIST-01: Loading state (skeleton ou spinner) em TODA operacao assincrona
+- UIST-02: Error state com mensagem clara e botao de retry
+- UIST-03: Empty state com orientacao de acao ("Nenhum item ainda. Clique em + para criar.")
+- UIST-04: Success feedback (toast) para TODA acao mutativa (criar, editar, deletar)
+- UIST-05: Disabled state em botoes durante submissao (evitar double-click)
+- UIST-06: Skeleton loading em vez de spinner generico para conteudo principal
+- UIST-07: Optimistic updates onde aplicavel (UI responde antes da API)
+- UIST-08: Confirmacao antes de acoes destrutivas (deletar, cancelar)
+
+## Error Handling (ERR)
+
+- ERR-01: Error boundary no layout raiz com fallback UI amigavel
+- ERR-02: Error boundary por feature/rota (erro em uma secao nao derruba o app)
+- ERR-03: Try/catch em toda operacao de API com mensagem amigavel
+- ERR-04: Tratamento de sessao expirada (redirect para login com mensagem)
+- ERR-05: Pagina 404 customizada com navegacao de volta
+- ERR-06: Tratamento de erros de rede (offline, timeout) com retry
+- ERR-07: Validacao server-side alem de client-side (nunca confiar so no front)
+- ERR-08: Logging de erros no console (dev) sem expor em producao
+
+## Performance (PERF)
+
+- PERF-01: Lazy loading de imagens (loading="lazy" ou next/image)
+- PERF-02: Code splitting por rota (dynamic imports / React.lazy)
+- PERF-03: Debounce em inputs de busca/filtro (300ms)
+- PERF-04: Pagination ou infinite scroll para listas > 20 items
+- PERF-05: Caching de queries (React Query / SWR / tRPC cache / staleTime)
+- PERF-06: Memoizacao de componentes pesados (React.memo, useMemo)
+- PERF-07: Evitar re-renders desnecessarios (keys corretas, deps do useEffect)
+- PERF-08: Compressao de imagens e assets (WebP, SVG onde possivel)
+- PERF-09: Prefetch de rotas provaveis (next/link prefetch)
+
+## Forms (FORM)
+
+- FORM-01: Validacao inline (ao sair do campo ou ao digitar, nao so no submit)
+- FORM-02: Mensagens de erro especificas por campo ("Email invalido" nao "Erro")
+- FORM-03: Botao desabilitado durante submissao com loading indicator
+- FORM-04: Autofocus no primeiro campo ao abrir form
+- FORM-05: Tab order logica (sem pular campos)
+- FORM-06: Defaults inteligentes onde possivel (data=hoje, moeda=BRL)
+- FORM-07: Preservar dados do form se usuario navegar e voltar
+- FORM-08: Mascara de input onde aplicavel (telefone, CPF, CEP, moeda)
+
+## Responsividade (RESP)
+
+- RESP-01: Layout funcional em 375px (iPhone SE) — sem overflow horizontal
+- RESP-02: Touch targets minimo 44x44px em mobile
+- RESP-03: Navegacao adaptada (hamburger/drawer em mobile)
+- RESP-04: Tabelas com scroll horizontal ou layout de cards em mobile
+- RESP-05: Modais fullscreen em mobile, dialog em desktop
+- RESP-06: Fonte legivel (min 14px body, min 12px labels)
+- RESP-07: Imagens responsivas (max-w-full, h-auto)
+
+## Meta/SEO (META)
+
+- META-01: Title unico por pagina
+- META-02: Meta description por pagina
+- META-03: OG tags (image, title, description) para compartilhamento social
+- META-04: Favicon (multiplos tamanhos)
+- META-05: Web manifest (PWA-ready)
+- META-06: Canonical URL
+- META-07: Robots meta (noindex para paginas privadas)
+
+## Acessibilidade (A11Y)
+
+- A11Y-01: Alt text em todas as imagens
+- A11Y-02: Labels associados a todos os inputs (htmlFor/id)
+- A11Y-03: Focus visible em elementos interativos (outline, ring)
+- A11Y-04: Keyboard navigation funcional (tab, enter, escape)
+- A11Y-05: Aria labels em botoes de icone (sem texto visivel)
+- A11Y-06: Hierarquia de headings (h1 > h2 > h3, sem pular niveis)
+- A11Y-07: Contraste minimo 4.5:1 em texto
+- A11Y-08: Skip to content link
+- A11Y-09: Landmarks (header, main, nav, footer)
+
+## Seguranca (SEC)
+
+- SEC-01: Protecao de rotas autenticadas (redirect se nao logado)
+- SEC-02: CSRF protection em forms
+- SEC-03: Sanitizacao de inputs (evitar XSS)
+- SEC-04: Rate limiting em endpoints sensiveis (login, signup, reset)
+- SEC-05: Headers de seguranca (CSP, X-Frame-Options, etc.)
+- SEC-06: Nao expor IDs sequenciais (usar UUID)
+- SEC-07: Env vars nunca expostas no client-side
+- SEC-08: RLS (Row Level Security) se usando Supabase
+
+## Visual Polish (POLISH)
+
+- POLISH-01: Hover states em todos elementos clicaveis
+- POLISH-02: Transicoes suaves em mudancas de estado (150-300ms)
+- POLISH-03: Consistencia de espacamento (usar escala: 4, 8, 12, 16, 24, 32, 48)
+- POLISH-04: Consistencia de cores (usar design tokens, nao hex hardcoded)
+- POLISH-05: Consistencia de tipografia (max 2 fontes, escala definida)
+- POLISH-06: Dark mode (opcional mas cada vez mais esperado)
+- POLISH-07: Favicon que funciona em light e dark mode

package/references/state-persistence.md

@@ -0,0 +1,74 @@
+# Persistência de Estado entre Sessões
+
+<purpose>
+Instruções para Claude Code salvar estado do projeto automaticamente, mesmo fora de comandos /up:.
+Quando o projeto tem `.plano/STATE.md`, TODA sessão produtiva deve registrar o que foi feito.
+</purpose>
+
+## Regra Principal
+
+Se o diretório `.plano/` existe com `STATE.md`, você DEVE salvar o estado da sessão ao final de trabalho significativo — independente de ter usado comandos `/up:` ou não.
+
+**Trabalho significativo** = qualquer coisa que mude o projeto de forma relevante:
+- Correção de bugs
+- Implementação de features (parcial ou completa)
+- Refatoração
+- Decisões de arquitetura
+- Debug e investigação com conclusões
+- Configuração de infra/deploy
+
+**NÃO é significativo** (não precisa salvar):
+- Leitura exploratória sem conclusão
+- Perguntas conceituais
+- Revisão sem alterações
+
+## Como Salvar
+
+Um único comando faz tudo (atualiza timestamp, descrição, atividade, e commita):
+
+```bash
+node "$HOME/.claude/up/bin/up-tools.cjs" state save-session --summary "descrição do que foi feito"
+```
+
+**Se houve decisão importante:**
+
+```bash
+node "$HOME/.claude/up/bin/up-tools.cjs" state save-session \
+  --summary "descrição do que foi feito" \
+  --decision "decisão tomada e por quê" \
+  --phase 2
+```
+
+**Se não quer commitar automaticamente:**
+
+```bash
+node "$HOME/.claude/up/bin/up-tools.cjs" state save-session --summary "descrição" --no-commit
+```
+
+## Quando Salvar
+
+1. **Final da conversa** — quando o trabalho está concluído ou pausado
+2. **Após resolver um bug** — mesmo que veio de continuação pós-agente
+3. **Após implementar algo** — mesmo parcialmente
+4. **Antes de sugerir /clear** — salvar estado garante continuidade
+
+## O que Escrever no --summary
+
+Seja específico e útil para a próxima sessão:
+
+- BOM: "Corrigido bug de autenticação — token expirado não redirecionava para login. Alterado middleware em src/auth.ts"
+- BOM: "Implementado componente de filtro de datas. Falta integrar com API de relatórios"
+- RUIM: "Feitas correções"
+- RUIM: "Trabalhado no projeto"
+
+## Integração com CLAUDE.md do Projeto
+
+Quando `/up:novo-projeto` ou `/up:modo-builder` inicializa um projeto, adicionar ao CLAUDE.md do projeto:
+
+```markdown
+## UP: Persistência de Estado
+
+Este projeto usa o sistema UP. Se `.plano/STATE.md` existir:
+- Ao final de trabalho significativo, salvar estado: `node "$HOME/.claude/up/bin/up-tools.cjs" state save-session --summary "o que foi feito"`
+- Isso garante continuidade entre sessões mesmo sem usar comandos /up:
+```

package/templates/builder-defaults.md

@@ -0,0 +1,73 @@
+# Builder Defaults Template
+
+Template para `~/.claude/up/builder-defaults.md` -- decisoes padrao do usuario para o modo builder.
+O usuario customiza uma vez e vale para todos os projetos criados com `/up:modo-builder`.
+
+<template>
+
+```markdown
+# Builder Defaults
+
+## Stack Padrao
+- Frontend: Next.js 15 (App Router) + Tailwind CSS + shadcn/ui
+- Backend: Supabase (Auth + Database + Edge Functions)
+- Linguagem: TypeScript (strict mode)
+- Package manager: pnpm
+- Testes: Vitest + Playwright
+
+## Decisoes de Design
+- Design system: shadcn/ui (tema neutro, customizar cores por projeto)
+- Responsividade: mobile-first
+- Dark mode: sim, com toggle
+- Fonte: Inter (UI) + JetBrains Mono (code)
+
+## Decisoes de Codigo
+- API: tRPC quando Next.js, REST quando Python/FastAPI
+- Auth: Supabase Auth
+- Validacao: Zod
+- Estado client: Zustand
+- Forms: React Hook Form + Zod resolver
+- ORM/DB: Supabase client (sem ORM adicional)
+
+## Padroes
+- Estrutura: feature-based (src/features/*)
+- Commits: conventional commits
+- Linter: ESLint + Prettier
+- Git: branch main, commits diretos
+
+## Nao usar
+- (liste aqui tecnologias que voce NAO quer em nenhum projeto)
+```
+
+</template>
+
+<guidelines>
+
+**Como o builder usa este arquivo:**
+
+1. Lido no inicio do modo builder (Estagio 1 - Intake)
+2. Qualquer decisao do briefing do usuario SOBRESCREVE os defaults
+3. Se o usuario especifica "usar Vue", o default de Next.js e ignorado
+4. Se o usuario NAO especifica frontend, o default de Next.js e usado
+5. A secao "Nao usar" e SEMPRE respeitada (nunca sobrescrita)
+
+**Hierarquia de decisao:**
+```
+Briefing do usuario (maior prioridade)
+  > Respostas das perguntas criticas
+    > builder-defaults.md do usuario
+      > Inferencia inteligente do sistema (menor prioridade)
+```
+
+**Inferencia inteligente (quando nao ha default nem briefing):**
+- Dominio financeiro → sugere tabelas, graficos, exportacao
+- Dominio social → sugere real-time, notificacoes, feeds
+- Dominio e-commerce → sugere pagamentos, carrinho, inventario
+- Dominio educacao → sugere progresso, quiz, certificados
+
+**O que NAO colocar nos defaults:**
+- Credenciais ou tokens (passados no briefing)
+- Decisoes especificas de projeto (schemas, nomes de tabelas)
+- Preferencias que mudam por projeto (cores, branding)
+
+</guidelines>