product-runner 0.5.0

package/profile-ssr/README.md

@@ -0,0 +1,51 @@
+# Perfil: Web SSR (Next.js Pages Router)
+
+Use este perfil em projetos que:
+
+- Rodam como **servidor web** com SSR/SSG (Next.js, Remix, etc.).
+- Têm **API routes** + **UI React**.
+- Precisam de **autenticação**, **formulários**, **componentes interativos**.
+- Persistem em DB via ORM (Prisma + Postgres como default), ou em
+  arquivos como acoplamento com outros sistemas.
+
+## Conteúdo
+
+| Arquivo | Pra quê |
+|---|---|
+| [code-patterns](./code-patterns.md) | Estrutura de pastas, schemas Zod, services, repository, mapper toOutput |
+| [api-patterns](./api-patterns.md) | API routes Next.js, validação, respostas, erros |
+| [ui-patterns](./ui-patterns.md) | Componentes React, formulários, Tailwind, **responsividade mobile** |
+| [claude-md.extension](../CLAUDE.md) | Seções específicas pra SSR (Next.js, deploy, comandos) |
+
+## Como combinar com `common/`
+
+Use o CLI — ele copia `common/` + este perfil pra `docs/` e gera o
+`CLAUDE.md` raiz (mescla template + extension, substitui `{...}`):
+
+```bash
+npx product-runner --name meu-projeto --profile ssr --port 3000 --dir .
+```
+
+Equivalente manual, se preferir sem npm:
+
+```bash
+cp common/*.md     meu-projeto/docs/
+cp profile-ssr/*.md meu-projeto/docs/
+cat common/claude-md.template.md profile-ssr/claude-md.extension.md \
+    > meu-projeto/CLAUDE.md
+```
+
+## Origem
+
+Conteúdo extraído de:
+- **DocManager** (`retro-20260419`) — base SSR Next.js + Prisma + shadcn/ui
+- **tradeBot** (`tradebot-202605`) — atualizações importadas:
+  - Princípios LLM-first (em [design-principles](./design-principles.md))
+  - Critérios meta M1/M2/M3 (em [spec-guide](./spec-guide.md))
+  - [_open-issues](../specs/_open-issues.md) (seed em `common/specs/`)
+  - Adições de responsividade mobile e integração com skill
+    `ui-design-system` (em [ui-patterns](./ui-patterns.md) deste perfil)
+
+## Anti-pattern: usar este perfil pra projeto CLI
+
+Stack assume request/response + UI. CLI sem isso. Use `profile-cli/`.

package/profile-ssr/api-patterns.md

@@ -0,0 +1,70 @@
+# API route patterns
+
+API routes são cascas finas — sem lógica de negócio.
+
+## Estrutura padrão
+
+```typescript
+export default async function handler(req, res) {
+  try {
+    switch (req.method) {
+      case "GET": return handleGet(req, res);
+      case "POST": return handlePost(req, res);
+      default:
+        res.setHeader("Allow", ["GET", "POST"]);
+        return res.status(405).json({ error: "Método não permitido" });
+    }
+  } catch (err) {
+    return handleError(err, res);
+  }
+}
+
+async function handlePost(req, res) {
+  const parsed = Schema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(400).json({
+      error: "Dados inválidos",
+      details: parsed.error.flatten().fieldErrors,
+    });
+  }
+  const result = await serviceFunction(parsed.data);
+  return res.status(201).json(result);
+}
+```
+
+## Tratamento de erros centralizado
+
+```typescript
+export function handleError(err: unknown, res) {
+  if (err instanceof DomainError) {
+    return res.status(err.statusCode).json({
+      error: err.message, code: err.code,
+    });
+  }
+  console.error("Erro inesperado:", err);
+  return res.status(500).json({ error: "Erro interno" });
+}
+```
+
+## Validação
+
+Sempre `safeParse`, nunca `parse` em API routes.
+Query params com `z.coerce` pra converter strings.
+
+## Respostas padronizadas
+
+| Situação             | Status | Body                    |
+|----------------------|--------|-------------------------|
+| Sucesso (read)       | 200    | `{ ...data }`           |
+| Sucesso (create)     | 201    | `{ ...data }`           |
+| Sucesso (no content) | 204    | vazio                   |
+| Aceito (async)       | 202    | `{ ...queue info }`     |
+| Validação falhou     | 400    | `{ error, details }`    |
+| Não encontrado       | 404    | `{ error, code }`       |
+| Conflito             | 409    | `{ error, code }`       |
+| Método não permitido | 405    | `{ error }` + Allow     |
+| Erro interno         | 500    | `{ error }` genérico    |
+
+## Upload de arquivos
+
+Desabilitar bodyParser, usar lib de parsing multipart.

package/profile-ssr/claude-md.extension.md

@@ -0,0 +1,113 @@
+<!--
+Extensão do CLAUDE.md — Perfil SSR.
+Este arquivo NÃO é concatenado: cada bloco abaixo declara, via diretiva
+`prod-runner-merge`, como dobra numa seção do template-base (common/claude-md.template.md).
+Modos: replace (troca a seção), append (acrescenta ao fim da seção),
+after (insere logo após a seção). Edite o conteúdo, não as diretivas.
+-->
+
+<!-- prod-runner-merge: append section="Stack" -->
+
+- **Framework:** Next.js (Pages Router)
+- **ORM:** Prisma + PostgreSQL (ou outro adapter quando configurado)
+- **UI:** Tailwind CSS + shadcn/ui
+- **Forms:** React Hook Form + Zod resolver
+- **Charts (se aplicável):** Recharts (default) ou TradingView lightweight
+  charts (séries financeiras)
+- **Background jobs (se aplicável):** BullMQ + Redis
+- **Deploy:** Docker + VPS (Vercel não cobre storage persistente +
+  background jobs)
+
+<!-- prod-runner-merge: replace section="Princípio central" -->
+
+### Princípio central
+
+Lógica de domínio desacoplada do framework. Services são TypeScript
+puro. API routes são cascas finas que validam e delegam pros services.
+Componentes UI consomem outputs tipados dos services.
+
+<!-- prod-runner-merge: replace section="Estrutura de pastas" -->
+
+### Estrutura de pastas
+
+```
+{project}/
+├── CLAUDE.md
+├── prisma/                           ← schema.prisma + migrations
+├── src/
+│   ├── pages/
+│   │   ├── api/                     ← API routes (cascas finas)
+│   │   └── {páginas SSR}
+│   ├── services/
+│   │   ├── {dominio}/
+│   │   │   ├── schema.ts             ← Zod entity + derivações
+│   │   │   └── repository.ts         ← Prisma queries + toOutput
+│   │   └── integrations/             ← clients de APIs externas
+│   ├── components/
+│   │   └── ui/                       ← shadcn/ui (gerados)
+│   └── lib/
+│       ├── prisma.ts
+│       ├── errors.ts
+│       └── {outros utilitários}
+├── scripts/
+├── specs/
+├── docs/
+└── docker-compose.yml                ← infra (Postgres, Redis se aplicável)
+```
+
+<!-- prod-runner-merge: append section="Convenções de código" -->
+
+### API Routes (SSR)
+
+- Validar com `Schema.safeParse()`.
+- Chamar o service e retornar o resultado.
+- Sem lógica de negócio.
+- Detalhe em [api-patterns](./docs/api-patterns.md).
+
+### UI (SSR)
+
+- Componentes shadcn/ui como base (gerados via CLI).
+- Tailwind utility classes — sem CSS modules.
+- Formulários com React Hook Form + Zod resolver.
+- **Responsividade mobile validada em todo componente novo** (M4 — ver
+  [ui-patterns](./docs/ui-patterns.md)).
+- Considerar skill `ui-design-system` em revisões de componente.
+
+### Validação visual no browser (SSR)
+
+Insubstituível — `tsc --noEmit` pega erros de tipo mas não de
+comportamento. Smoke check humano em mobile (375x667) e desktop
+(1280x720) faz parte do M4.
+
+<!-- prod-runner-merge: replace section="Comandos úteis" -->
+
+## Comandos úteis
+
+```bash
+docker compose up -d              # infra (Postgres, Redis)
+npm install                       # deps
+npx prisma migrate dev            # migrations
+npx prisma generate               # client
+npm run dev                       # dev server (port {PORT})
+npm test                          # testes
+npx tsc --noEmit                  # typecheck
+npx shadcn@latest add <comp>      # adicionar componente
+npm run format                    # formatar tudo
+```
+
+Configurar port fixo no `package.json` (`"dev": "next dev -p {PORT}"`) pra
+evitar mudança entre sessões. Code deve reportar o port real no output ao
+iniciar o dev server.
+
+<!-- prod-runner-merge: replace section="Configuração" -->
+
+## Configuração
+
+| Arquivo                | Conteúdo              | Comitado? |
+| ---------------------- | --------------------- | --------- |
+| `.env`                 | DATABASE_URL, secrets | ❌ NUNCA  |
+| `.env.example`         | Mesmas chaves sem valor | ✅      |
+| `prisma/schema.prisma` | Schema do DB          | ✅        |
+| `next.config.js`       | Config Next           | ✅        |
+| `tailwind.config.ts`   | Config Tailwind       | ✅        |
+| `components.json`      | Config shadcn/ui      | ✅        |

package/profile-ssr/code-patterns.md

@@ -0,0 +1,175 @@
+# Data patterns
+
+Padrões para definição de schemas, derivação de tipos,
+e transformação de dados entre camadas.
+
+## Princípio
+
+Cada domínio tem UM arquivo `schema.ts` com:
+1. Entity base (espelha o ORM model)
+2. Refs de relações (formas simplificadas de entities relacionadas)
+3. Inputs (derivados da entity por pick/extend)
+4. Outputs (derivados da entity por omit/extend)
+
+Nunca escrever interfaces ou types manualmente.
+Sempre derivar do schema de validação e inferir tipos.
+
+## Entity base
+
+```typescript
+// services/{domínio}/schema.ts
+
+export const {Entity}Entity = z.object({
+  id: z.string().uuid(),
+  // ... espelha todos os campos do ORM model
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+export type {Entity}Entity = z.infer<typeof {Entity}Entity>;
+```
+
+Regras:
+- Nomes de campos idênticos ao ORM model.
+- DateTime → `z.string().datetime()`.
+- Nullable → `.nullable()`.
+- Enums como `z.enum([...])`.
+
+## Refs de relações
+
+Formas simplificadas pra usar como campos em outputs:
+
+```typescript
+export const {Related}Ref = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+});
+```
+
+## Derivação de inputs
+
+```typescript
+export const Create{Entity}Input = {Entity}Entity
+  .pick({ /* campos editáveis */ })
+  .partial()
+  .extend({ /* campos adicionais */ });
+
+export type Create{Entity}Input = z.infer<typeof Create{Entity}Input>;
+```
+
+Regras:
+- Usar `.shape.fieldName` pra referenciar tipos da entity.
+- Usar `.unwrap()` pra remover nullable quando obrigatório no input.
+
+## Derivação de outputs
+
+```typescript
+export const {Entity}Output = {Entity}Entity
+  .omit({ /* campos internos */ })
+  .extend({
+    // relações resolvidas
+    {related}: {Related}Ref.nullable(),
+  });
+```
+
+Regras:
+- Omitir campos internos (paths, IDs de FK).
+- Substituir FK IDs por refs resolvidas.
+
+## Mapper toOutput
+
+```typescript
+function toOutput(doc: any): {Entity}OutputType {
+  return {
+    // mapear campos, resolver relações
+    createdAt: doc.createdAt.toISOString(),
+  };
+}
+```
+
+## Validação de output em dev
+
+```typescript
+if (process.env.NODE_ENV === "development") {
+  return {Entity}Output.parse(data);
+}
+```
+
+---
+
+# Service patterns
+
+Padrões para services, repositories, erros e integrações.
+
+## Estrutura de um domínio
+
+```
+services/{domínio}/
+├── schema.ts         ← entity + inputs + outputs
+├── repository.ts     ← CRUD via ORM, mapper
+├── {lógica}.ts       ← lógica de negócio específica
+```
+
+Regras:
+- `repository.ts` faz queries e retorna outputs tipados.
+- Outros arquivos contêm lógica de negócio.
+- Services podem importar outros services.
+- Services NUNCA importam tipos do framework.
+
+## Repository
+
+```typescript
+const defaultInclude = { /* relações padrão */ } as const;
+
+export async function create{Entity}(
+  input: Create{Entity}Input
+): Promise<{Entity}Output> {
+  const record = await orm.{entity}.create({
+    data: { /* ... */ },
+    include: defaultInclude,
+  });
+  return toOutput(record);
+}
+```
+
+## Erros de domínio
+
+```typescript
+export class DomainError extends Error {
+  constructor(message: string, public code: string, public statusCode: number = 400) {
+    super(message);
+  }
+}
+
+export class NotFoundError extends DomainError { /* 404 */ }
+export class ConflictError extends DomainError { /* 409 */ }
+export class ValidationError extends DomainError { /* 400 */ }
+```
+
+## Regras de integridade
+
+Validações que o ORM não cobre ficam no service:
+- XOR constraints (campo A OU B, nunca ambos)
+- Prevenção de ciclos (auto-referência hierárquica)
+- Recálculo de campos derivados
+
+## Integrações externas
+
+```
+services/integrations/
+├── {provider}.ts     ← client isolado, tipos simples
+```
+
+- Retornam tipos simples, não outputs de domínio.
+- O service de domínio orquestra e converte resultados.
+- Credenciais via env vars, nunca hardcoded.
+
+## Transações
+
+```typescript
+await orm.$transaction(async (tx) => {
+  // operações atômicas
+});
+```
+
+Usar sempre que uma operação envolve múltiplas writes.

package/profile-ssr/ui-patterns.md

@@ -0,0 +1,97 @@
+# UI patterns
+
+Padrões para componentes, páginas, formulários e estilização.
+
+## Estrutura
+
+```
+src/components/
+├── ui/              ← componentes da lib (shadcn, etc) — gerados
+├── {componente}.tsx  ← componentes do projeto
+```
+
+## Estilização
+
+Tailwind utility classes para tudo. Sem CSS modules,
+sem styled-components, sem arquivos CSS customizados.
+
+## Formulários
+
+Usar React Hook Form + Zod resolver, reutilizando
+os schemas do service:
+
+```typescript
+const form = useForm<InputType>({
+  resolver: zodResolver(InputSchema),
+  defaultValues: { /* ... */ },
+});
+```
+
+Regras:
+- NUNCA duplicar validação — reutilizar o schema do service.
+- Erros inline via FormMessage do componente lib.
+- Erros de API via toast.
+
+## Páginas
+
+- Tipar dados com os types de output do service.
+- Loading states com skeleton.
+- Empty states com mensagem + ação sugerida.
+- Layout consistente.
+
+## Componentes da lib (ex: shadcn/ui)
+
+- Sempre usar CLI pra instalar: `npx shadcn@latest add <comp>`.
+- Nunca criar componentes da lib manualmente.
+- Editar depois de gerado é permitido.
+
+## Responsividade mobile
+
+Toda página/componente novo é validado em **dois viewports** antes
+de declarar pronto:
+
+| Viewport | Resolução | Comportamento esperado |
+|---|---|---|
+| Mobile | 375 × 667 (iPhone SE) | Sem scroll horizontal; touch targets ≥ 44px; menus colapsam |
+| Desktop | 1280 × 720 | Layout completo; hover states funcionam |
+
+### Regras de Tailwind
+
+- Mobile-first: classes sem prefix são pra mobile; `md:`, `lg:`
+  são extensões pra telas maiores.
+- Evitar `w-screen` puro (causa scroll horizontal); usar `w-full`.
+- Espaçamentos generosos em mobile (`p-4`, `gap-4`) que diminuem
+  em desktop (`md:p-6`, `lg:p-8`).
+- Tipografia: `text-base` mobile, `md:text-lg` desktop quando
+  precisar de hierarquia visual.
+
+### Anti-patterns
+
+- ❌ `min-w-[800px]` — causa scroll horizontal em mobile.
+- ❌ `fixed` sem prever que mobile pode cobrir conteúdo.
+- ❌ Testar só em desktop e descobrir o mobile depois.
+
+## Skill de UI/UX (suporte externo)
+
+Considerar invocar a skill `ui-design-system` (Cowork) ao revisar
+componentes novos pra obter:
+- Análise de hierarquia visual.
+- Identificação de inconsistências com design system existente.
+- Indicação de pontos de responsividade frágeis.
+- Sugestões de spec-anchored (componentes para o Code aplicar
+  consistentemente).
+
+## Critério meta M4 — UI responsiva
+
+Toda spec que cria/altera componente UI inclui no checklist:
+
+- [ ] Componente funciona em viewport `375x667` (mobile) sem scroll
+      horizontal.
+- [ ] Touch targets ≥ 44px em mobile (botões, links clicáveis).
+- [ ] Componente funciona em viewport `1280x720` (desktop) com
+      hover states ativos.
+- [ ] Code rodou screenshot ou descreveu o layout nos dois viewports
+      no report final.
+
+M4 é critério meta da própria spec — referenciar como "aplicam-se
+M1, M2, M3, M4" em specs de UI.