stealthos-cli 0.1.0-alpha.2 → 0.1.0-alpha.4

package/ai/server/src/snapshot/snapshot-diff.ts

@@ -0,0 +1,86 @@
+import { readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ProjectState, SnapshotDiff, SnapshotManifest } from "../types.js";
+
+export async function listSnapshots(
+  projectRoot: string,
+): Promise<SnapshotManifest[]> {
+  const dir = join(projectRoot, ".ai", "snapshots");
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const out: SnapshotManifest[] = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const manifestPath = join(dir, e.name, "manifest.json");
+    if (!existsSync(manifestPath)) continue;
+    try {
+      const txt = await readFile(manifestPath, "utf8");
+      out.push(JSON.parse(txt) as SnapshotManifest);
+    } catch {
+      // ignore malformed
+    }
+  }
+  return out.sort((a, b) => (a.created_at < b.created_at ? 1 : -1));
+}
+
+export async function diffSnapshots(
+  projectRoot: string,
+  idA: string,
+  idB: string,
+): Promise<SnapshotDiff> {
+  const dir = join(projectRoot, ".ai", "snapshots");
+  const a = await loadManifest(dir, idA);
+  const b = await loadManifest(dir, idB);
+  const stateA = await loadState(dir, idA);
+  const stateB = await loadState(dir, idB);
+
+  const filesA = new Set(Object.keys(a.file_hashes));
+  const filesB = new Set(Object.keys(b.file_hashes));
+  const files_added: string[] = [];
+  const files_removed: string[] = [];
+  const files_changed: string[] = [];
+  for (const f of filesB) {
+    if (!filesA.has(f)) files_added.push(f);
+    else if (a.file_hashes[f] !== b.file_hashes[f]) files_changed.push(f);
+  }
+  for (const f of filesA) {
+    if (!filesB.has(f)) files_removed.push(f);
+  }
+
+  const modulesA = new Set(stateA?.modules.map((m) => m.id) ?? []);
+  const modulesB = new Set(stateB?.modules.map((m) => m.id) ?? []);
+  const modules_added: string[] = [];
+  const modules_removed: string[] = [];
+  for (const m of modulesB) if (!modulesA.has(m)) modules_added.push(m);
+  for (const m of modulesA) if (!modulesB.has(m)) modules_removed.push(m);
+
+  const smells_delta =
+    (stateB?.smells.length ?? 0) - (stateA?.smells.length ?? 0);
+
+  return {
+    a: idA,
+    b: idB,
+    files_added,
+    files_removed,
+    files_changed,
+    modules_added,
+    modules_removed,
+    decisions_added: 0,
+    smells_delta,
+  };
+}
+
+async function loadManifest(snapDir: string, id: string): Promise<SnapshotManifest> {
+  const txt = await readFile(join(snapDir, id, "manifest.json"), "utf8");
+  return JSON.parse(txt) as SnapshotManifest;
+}
+
+async function loadState(snapDir: string, id: string): Promise<ProjectState | null> {
+  try {
+    const txt = await readFile(join(snapDir, id, "state.json"), "utf8");
+    return JSON.parse(txt) as ProjectState;
+  } catch {
+    return null;
+  }
+}

package/ai/server/src/snapshot/snapshot-restore.ts

@@ -0,0 +1,14 @@
+export interface RestoreOptions {
+  id: string;
+  dryRun?: boolean;
+}
+
+export async function restoreSnapshot(
+  _projectRoot: string,
+  _options: RestoreOptions,
+): Promise<never> {
+  throw new Error(
+    "restore not implemented in v0.1 — snapshots are read-only in this version. " +
+      "Use snapshotList/snapshotDiff for inspection. Restore is on the v0.2 roadmap.",
+  );
+}

package/ai/server/src/types.ts

@@ -0,0 +1,94 @@
+export interface ProjectState {
+  version: string;
+  generated_at: string;
+  project_root: string;
+  stack: StackInfo;
+  modules: ModuleInfo[];
+  graph: DependencyGraph;
+  smells: Smell[];
+  stats: ProjectStats;
+}
+
+export interface StackInfo {
+  languages: string[];
+  frameworks: string[];
+  package_manager?: string;
+  databases?: string[];
+  test_frameworks?: string[];
+  linters?: string[];
+  ci_cd?: string[];
+}
+
+export interface ModuleInfo {
+  id: string;
+  name: string;
+  path: string;
+  kind: "file" | "directory";
+  language: string;
+  size_lines: number;
+  imports: string[];
+  exports: string[];
+  responsibilities?: string[];
+}
+
+export interface DependencyGraph {
+  nodes: string[];
+  edges: Array<{ from: string; to: string }>;
+  cycles: string[][];
+}
+
+export interface Smell {
+  kind:
+    | "circular_dependency"
+    | "large_file"
+    | "large_function"
+    | "dead_code"
+    | "todo_comment"
+    | "fixme_comment";
+  severity: "low" | "medium" | "high";
+  location: { file: string; line?: number };
+  message: string;
+}
+
+export interface ProjectStats {
+  total_files: number;
+  total_lines: number;
+  files_by_language: Record<string, number>;
+  largest_files: Array<{ path: string; lines: number }>;
+}
+
+export interface ContextPackage {
+  intent: string;
+  generated_at: string;
+  estimated_tokens: number;
+  source_state_hash: string;
+  modules_included: string[];
+  markdown: string;
+}
+
+export interface SnapshotManifest {
+  id: string;
+  label: string;
+  created_at: string;
+  project_root: string;
+  state_file: string;
+  summary_file: string;
+  file_hashes: Record<string, string>;
+  stats: {
+    total_files_hashed: number;
+    modules: number;
+    smells: number;
+  };
+}
+
+export interface SnapshotDiff {
+  a: string;
+  b: string;
+  files_added: string[];
+  files_removed: string[];
+  files_changed: string[];
+  modules_added: string[];
+  modules_removed: string[];
+  decisions_added: number;
+  smells_delta: number;
+}

package/ai/server/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "sourceMap": false,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": false
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/ai/skills/architecture-design.md

@@ -0,0 +1,82 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~600
+load: architecture, design_decision
+triggers: arquitetura, architecture, design, padrão, microserviço, monorepo
+---
+
+# Skill: Architecture Design
+
+## Princípios
+
+- **YAGNI até dor real.** Não desenhe para escala que não existe.
+- **Conway's Law.** A arquitetura tende a refletir a estrutura do time.
+- **Reversibilidade.** Decisões caras devem ser tomadas tarde; baratas, cedo.
+- **Trade-offs explícitos.** Toda decisão tem um custo — registrar qual.
+
+## Quando reformular arquitetura
+
+- A regra atual exige >3 hops para entender um fluxo simples.
+- Mudanças simples exigem alterar >5 arquivos não relacionados.
+- Acoplamento bloqueia testes em isolamento.
+- Performance degradou e não há caminho claro de otimização.
+
+## Camadas Recomendadas
+
+```
+Presentation (UI / API handlers)
+    ↓
+Application (casos de uso, orquestração)
+    ↓
+Domain (entidades, regras de negócio puras)
+    ↓
+Infrastructure (DB, HTTP clients, filas)
+```
+
+- Dependências apontam para dentro (Clean Architecture / Hexagonal).
+- Domain não conhece infrastructure.
+
+## Decomposição
+
+| Sintoma | Resposta |
+|---|---|
+| Módulo > 1000 linhas | Quebrar por responsabilidade |
+| Duas equipes editando o mesmo arquivo | Quebrar por ownership |
+| Tempo de build inaceitável | Quebrar em pacotes/módulos |
+| Deploy acoplado entre features independentes | Considerar microserviço |
+
+## Microserviços — usar quando
+
+- Times independentes precisam liberar em cadências diferentes.
+- Escala MUITO diferente entre componentes.
+- Tolerância a falha precisa ser isolada.
+
+## Microserviços — NÃO usar quando
+
+- Time único, projeto novo.
+- Transações atravessam serviços frequentemente.
+- Latência inter-serviço é crítica.
+
+## ADR (Architecture Decision Record)
+
+Toda decisão arquitetural vai para `memory/decisions.md` no formato:
+
+```
+## ADR-NNN — Título
+Data: AAAA-MM-DD
+Status: Proposto | Aceito | Substituído por ADR-NNN
+
+### Contexto
+O que motivou a decisão.
+
+### Decisão
+O que foi decidido.
+
+### Consequências
+Trade-offs aceitos.
+
+### Alternativas consideradas
+Por que NÃO foram escolhidas.
+```

package/ai/skills/backend-engineering.md

@@ -0,0 +1,57 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~600
+load: backend, api
+triggers: endpoint, api, rest, graphql, controller, route, middleware
+---
+
+# Skill: Backend Engineering
+
+## Princípios
+
+- **Boundaries explícitos.** Entrada validada, saída tipada, erros mapeados.
+- **Idempotência por padrão** em endpoints de escrita quando possível (chaves de idempotência).
+- **Stateless services** > estado em memória. Estado vai para DB/cache/fila.
+- **Falha rápida.** Validar input na borda, não em camadas profundas.
+
+## API Design
+
+- REST: substantivos + verbos HTTP. `POST /orders`, não `POST /createOrder`.
+- Status codes corretos: 2xx sucesso, 4xx erro do cliente, 5xx erro do servidor.
+- Versionamento explícito (`/v1/`, header, ou query) desde o dia 1.
+- Paginação padronizada (`?limit=&cursor=`), nunca offset puro em datasets grandes.
+- Erros estruturados: `{ "error": { "code": "...", "message": "...", "details": {...} } }`.
+
+## Validação
+
+- Schema na borda (Zod, Pydantic, JSON Schema).
+- Reject unknown fields por padrão.
+- Limites: tamanho de payload, profundidade de objetos, tamanho de strings.
+
+## Persistência
+
+- Transações para operações multi-step.
+- Migrations versionadas, reversíveis quando possível.
+- Não fazer queries em loop (N+1). Usar join/batch.
+- Índices baseados em queries reais, não em palpite.
+
+## Concorrência
+
+- Locks otimistas (versionamento de linha) > pessimistas.
+- Filas para trabalho async; nunca processar pesado dentro do request HTTP.
+- Retry com backoff exponencial + jitter.
+
+## Observabilidade
+
+- Logs estruturados (JSON) com `request_id`, `user_id`, `trace_id`.
+- Métricas: latência (p50/p95/p99), taxa de erro, throughput.
+- Health checks: `/healthz` (vivo) e `/readyz` (pronto para tráfego).
+
+## Erros comuns a evitar
+
+- Vazar stack trace para o cliente.
+- Esconder erros internos atrás de 200 OK.
+- Tornar endpoints "convenientes" misturando 5 ações em um.
+- Acoplar lógica de negócio à camada HTTP.

package/ai/skills/database-design.md

@@ -0,0 +1,76 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~600
+load: database
+triggers: db, database, banco, sql, query, migration, schema, índice, postgres, mysql, mongo
+---
+
+# Skill: Database Design
+
+## Princípios
+
+- **Modelar o domínio, não a UI.** A tela muda, o modelo deveria mudar menos.
+- **Normalizar primeiro, desnormalizar com motivo.** 3NF como ponto de partida.
+- **Constraints no banco**, não só na aplicação. NOT NULL, FK, UNIQUE, CHECK.
+- **Migrations são código de produção.** Versionadas, revisadas, reversíveis.
+
+## Escolha de DB
+
+| Caso | Escolha típica |
+|---|---|
+| OLTP relacional, transações | PostgreSQL / MySQL |
+| Documentos flexíveis | MongoDB (com cuidado) ou JSONB no Postgres |
+| Cache / sessões | Redis |
+| Full-text search | Elasticsearch / Meilisearch / Postgres FTS |
+| Time-series | TimescaleDB / InfluxDB |
+| Grafos | Neo4j (raro; geralmente Postgres com recursivo basta) |
+
+## Schema
+
+- IDs: UUID v7 ou ULID (ordenáveis) > UUID v4 > auto-increment.
+- Timestamps: `created_at`, `updated_at` em UTC, sempre.
+- Soft delete: `deleted_at` nullable; nunca remover linhas com histórico relevante.
+- Enums em coluna com CHECK ou tabela de lookup; não string livre.
+
+## Índices
+
+- Em colunas usadas em `WHERE`, `JOIN`, `ORDER BY`.
+- Composto na ordem de seletividade.
+- Não indexar tudo — índice tem custo de escrita.
+- Verificar uso real com `EXPLAIN ANALYZE` antes de criar.
+
+## Migrations
+
+- Uma migration = uma mudança lógica.
+- Reversível quando possível (`up` + `down`).
+- Adicionar coluna NOT NULL: 1) adicionar nullable + default 2) backfill 3) ALTER para NOT NULL.
+- Lock-aware em tabelas grandes (PostgreSQL: `CREATE INDEX CONCURRENTLY`).
+
+## Queries
+
+- Parametrizadas SEMPRE (prevenção de SQL injection).
+- Evitar `SELECT *` em produção — listar colunas.
+- LIMIT obrigatório em queries que retornam lista.
+- Detectar N+1 (logging de queries em dev; ORMs têm flag).
+
+## Transações
+
+- Tão curtas quanto possível.
+- Não fazer I/O externo dentro de transação.
+- Isolation level explícito quando importa (READ COMMITTED é default usual).
+- Deadlock → ordenar acessos a recursos consistentemente.
+
+## Backup e recovery
+
+- Backup automatizado, retenção definida.
+- TESTAR restore periodicamente — backup não testado é teoria.
+- PITR (point-in-time recovery) em produção.
+
+## Anti-padrões
+
+- EAV (entity-attribute-value) genérico "para flexibilidade".
+- Strings concatenadas para queries dinâmicas.
+- `OFFSET N` em paginação de tabela grande (usar cursor).
+- Múltiplas booleans para estados mutuamente exclusivos (usar enum).

package/ai/skills/frontend-engineering.md

@@ -0,0 +1,63 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~600
+load: frontend, ui
+triggers: ui, ux, component, react, vue, svelte, form, css, a11y
+---
+
+# Skill: Frontend Engineering
+
+## Princípios
+
+- **Componentes pequenos, com responsabilidade única.**
+- **Estado o mais próximo possível de onde é usado.** Subir apenas quando compartilhado.
+- **Acessibilidade não é opcional.** Roles, labels, contraste, navegação por teclado.
+- **Performance percebida > performance bruta.** Skeleton, optimistic UI, lazy load.
+
+## Estrutura
+
+- Separar **UI puro** (apresentação) de **container** (estado/fetch).
+- Hooks customizados para lógica reutilizável.
+- Tipos em todo lugar (TS estrito; `any` é code smell).
+
+## Estado
+
+| Tipo | Onde mora |
+|---|---|
+| UI local (input, toggle) | `useState` no componente |
+| Compartilhado entre poucos | Context ou prop drilling raso |
+| Global cliente | Zustand, Jotai, Redux (escolher um) |
+| Servidor / cache | React Query, SWR, Apollo |
+| URL | Query params, route state |
+
+## Renderização
+
+- Evitar re-render desnecessário: memoização SÓ depois de medir, não preventivamente.
+- Lista grande → virtualização (react-window, tanstack-virtual).
+- Imagens → `srcset`, formatos modernos (WebP/AVIF), lazy loading.
+
+## Forms
+
+- Validação client-side imediata + server-side autoritativa.
+- Estado controlado para forms complexos; uncontrolled para forms triviais.
+- Disable do submit enquanto pending. Loading state visível.
+
+## Estilo
+
+- Token-based (cores, espaçamentos, tipografia) — nunca valor cru.
+- Mobile-first.
+- Dark mode considerado desde o design, não retrofit.
+
+## Erros e Loading
+
+- Toda chamada async tem 3 estados visuais: idle, loading, error.
+- Mensagens de erro acionáveis ("Conexão falhou. Tentar novamente"), não genéricas ("Algo deu errado").
+
+## Anti-padrões
+
+- `useEffect` para sincronizar com estado externo quando `useMemo`/derivação resolveria.
+- Re-fetch a cada navegação quando cache resolveria.
+- DOM imperativo dentro de React (`document.querySelector`).
+- CSS global que vaza em tudo.

package/ai/skills/performance.md

@@ -0,0 +1,73 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~500
+load: performance
+triggers: lento, slow, performance, latência, p95, p99, gargalo, otimizar
+---
+
+# Skill: Performance
+
+## Princípio
+
+> Medir > supor. Otimizar > especular. Profiling > opinião.
+
+## Ordem de Investigação
+
+1. **Reproduzir** o problema com workload realista.
+2. **Medir** com profiler (não estimar).
+3. **Identificar** o hot path (geralmente <5% do código consome >90% do tempo).
+4. **Atacar** a maior contribuição primeiro.
+5. **Validar** com novo profile.
+
+## Métricas-alvo (referência)
+
+| Camada | Métrica | Alvo razoável |
+|---|---|---|
+| HTTP API | p99 latency | < 300ms |
+| Frontend | LCP | < 2.5s |
+| Frontend | INP | < 200ms |
+| DB query | p99 | < 100ms |
+| Background job | throughput | depende do volume |
+
+## Padrões de otimização (em ordem de impacto)
+
+### Algoritmo
+- O(n²) → O(n log n) ou O(n) com hash.
+- Eliminar trabalho redundante (memoize, cache).
+
+### I/O
+- Batch (N requests → 1).
+- Paralelizar requests independentes.
+- Streaming em vez de carregar tudo.
+
+### Banco
+- Índice em coluna usada em WHERE/ORDER BY.
+- Evitar N+1 (JOIN ou batch fetch).
+- Paginar resultados grandes.
+- Read replicas para leitura pesada.
+
+### Cache
+- Cache na camada mais próxima do consumo.
+- TTL adequado ao churn dos dados.
+- Invalidação explícita > TTL ingênuo.
+
+### Concorrência
+- Async para I/O-bound.
+- Pool de workers para CPU-bound.
+- Backpressure para evitar buffer overflow.
+
+## Anti-padrões
+
+- "Otimização preventiva" sem profile.
+- Cache em tudo (cache miss + invalidação fica pior que sem cache).
+- Paralelizar antes de garantir thread-safety.
+- Trocar lib por outra "mais rápida" sem medir o ganho real.
+
+## Registro
+
+Toda otimização não-trivial vai para `memory/decisions.md` com:
+- Métrica antes / depois
+- Como foi medida
+- Custo (complexidade, manutenção)

package/ai/skills/scalability.md

@@ -0,0 +1,84 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~550
+load: scaling
+triggers: escalar, scale, scaling, tráfego, sharding, replicação, fila, queue
+---
+
+# Skill: Scalability
+
+## Princípio
+
+> Escala que não existe é problema imaginário. Mas decisões erradas cedo são caras de desfazer.
+
+## Eixos de Escala
+
+1. **Vertical** (mais CPU/RAM): rápido, finito, simples.
+2. **Horizontal** (mais máquinas): exige stateless, harder, ilimitado em teoria.
+3. **Funcional** (split por serviço/domínio): exige boundaries claros.
+4. **Dados** (sharding/partitioning): último recurso para datasets gigantes.
+
+Ordem recomendada: vertical → horizontal → funcional → dados.
+
+## Stateless
+
+- Estado fora do processo (Redis, DB, S3).
+- Sessões via cookie assinado ou store externa, não memória do worker.
+- Workers descartáveis a qualquer momento.
+
+## Caching em Camadas
+
+```
+Browser cache
+    ↓
+CDN (estáticos + edge cache)
+    ↓
+Reverse proxy cache (Varnish, Nginx)
+    ↓
+Application cache (Redis)
+    ↓
+DB query cache
+```
+
+Cada camada absorve uma classe de carga. Comece pela mais barata (CDN) antes da mais cara (DB cache).
+
+## Async + Filas
+
+- Trabalho que não precisa ser síncrono → fila (SQS, RabbitMQ, Redis Streams).
+- Worker pool processa em background.
+- Webhook recebido → ack rápido + enfileira; nunca processar dentro do request.
+
+## Read vs Write
+
+- Leitura escala mais barato que escrita.
+- Read replicas para leitura pesada.
+- CQRS quando read e write têm modelos muito diferentes.
+- Write: batch, async, particionar.
+
+## Particionamento
+
+- Por chave natural (user_id, tenant_id, region).
+- Hot partition é o pior cenário — distribuição uniforme importa.
+- Reparticionamento é doloroso → escolher chave com folga.
+
+## Limites e Backpressure
+
+- Rate limit por API key / IP / user.
+- Circuit breaker em chamadas a serviços externos.
+- Bulkhead: pools separados para cargas diferentes.
+- Timeout em TODA chamada de rede.
+
+## Observabilidade em Escala
+
+- Sampling de traces (não trace 100% em alto throughput).
+- Métricas agregadas + traces para amostras suspeitas.
+- Alertas em sintomas (latência, erro) > em causas (CPU alto pode ser ok).
+
+## Anti-padrões
+
+- Microserviços antes de hitting limites do monolito.
+- Sharding de DB antes de explorar índices/queries.
+- Otimizar para 1000x do tráfego atual.
+- Kafka + Kubernetes + 12 ferramentas para 100 usuários.