product-runner 0.5.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "product-runner",
+  "version": "0.5.0",
+  "description": "Scaffold de docs para projetos TypeScript com desenvolvimento assistido por AI: gera CLAUDE.md + docs/ a partir de templates vivos (common + perfil cli/ssr).",
+  "type": "module",
+  "bin": {
+    "product-runner": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "common",
+    "profile-cli",
+    "profile-ssr",
+    "migrations"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "node --experimental-strip-types src/cli.ts",
+    "test": "npm run build && node --test dist/*.test.js",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "scaffold",
+    "template",
+    "claude",
+    "ai-assisted",
+    "typescript",
+    "docs"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/profile-cli/README.md

@@ -0,0 +1,54 @@
+# Perfil: CLI / script Node em loop
+
+Use este perfil em projetos que:
+
+- Rodam como **script Node terminal** (não servidor HTTP).
+- Têm um **loop principal** (infinito ou periódico).
+- Fazem I/O com **lib externa** (broker, AI API, queue, etc.) que precisa ser isolada.
+- Persistem estado via **arquivos locais** (JSON) ou DB.
+- Não têm UI — observability via logs + arquivos consumidos por
+  ferramentas tipo OpenSearch/Kibana.
+
+## Conteúdo
+
+| Arquivo | Pra quê |
+|---|---|
+| [code-patterns](./code-patterns.md) | Estrutura de pastas, schemas Zod, port/adapter pra integrações, padrões de erro, persistência |
+| [claude-md.extension](../CLAUDE.md) | Seções específicas pra CLI (comandos `npm run`, configuração `.env`, observability via arquivos) |
+
+## 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 cli --dir .
+```
+
+Equivalente manual, se preferir sem npm:
+
+```bash
+cp common/*.md     meu-projeto/docs/
+cp profile-cli/*.md meu-projeto/docs/
+cat common/claude-md.template.md profile-cli/claude-md.extension.md \
+    > meu-projeto/CLAUDE.md
+# Adapta valores entre {} pelos do projeto.
+```
+
+## Origem
+
+Conteúdo extraído de:
+- **tradeBot** (snapshot tradebot-202605, refactor 11 specs)
+
+Adaptações feitas pra generalizar:
+- `BrokerClient` virou termo genérico "ExternalAdapter" em alguns
+  exemplos.
+- `tradeBot`/`Binance` → `{ProjectName}` / `{ExternalSystem}` quando
+  apropriado.
+- Defaults específicos de trade (multipliers, etc.) foram trocados
+  por placeholders.
+
+## Anti-pattern: usar este perfil pra projeto SSR
+
+Web SSR tem fronteira HTTP, request/response, UI. Estrutura aqui
+não cobre. Use `profile-ssr/` no lugar.

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

@@ -0,0 +1,102 @@
+<!--
+Extensão do CLAUDE.md — Perfil CLI.
+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" -->
+
+- **Broker / lib externa:** {ex: `@binance/connector`, `openai`, etc.} —
+  abstraído via `BrokerClient` (port/adapter)
+- **Config:** `dotenv` + `.env`
+- **Persistência:** arquivos JSON locais (`actualState.json`, `history/`)
+- **Observability:** arquivos JSON formato Kibana consumidos por OpenSearch
+  local (ou similar)
+- **Containerização:** Docker (`docker-compose.yml`) — opcional
+
+<!-- prod-runner-merge: replace section="Princípio central" -->
+
+### Princípio central
+
+Lógica de domínio (cálculo, decisão, regras) é código TypeScript
+puro, sem acoplamento com lib externa, file system ou env. Acesso
+à lib externa via interface (port). Persistência via funções
+dedicadas. Loop principal é casca fina que orquestra.
+
+<!-- prod-runner-merge: replace section="Estrutura de pastas" -->
+
+### Estrutura de pastas
+
+```
+{project}/
+├── CLAUDE.md
+├── index.ts                     ← entrypoint mínimo (loop fino)
+├── docs/
+├── specs/
+├── domain/
+│   ├── {externalAdapter}.ts     ← interface (port)
+│   └── errors.ts                ← classes de erro de domínio
+├── services/
+│   ├── {dominio}/               ← lógica pura + schemas
+│   ├── persistence/             ← load/save JSON, mappers
+│   └── integrations/            ← adapters (implementações dos ports)
+├── tests/
+└── dist/                        ← outDir do tsc (gitignored)
+```
+
+<!-- prod-runner-merge: replace section="Comandos úteis" -->
+
+## Comandos úteis
+
+```bash
+npm install                       # deps
+npm run start                     # compilar e rodar (loop infinito)
+npm run start:reset               # apaga estado e recomeça do zero (se aplicável)
+npm test                          # testes
+npx tsc --noEmit                  # typecheck
+docker compose up -d              # infra (OpenSearch local, etc.) — opcional
+```
+
+<!-- prod-runner-merge: replace section="Configuração" -->
+
+## Configuração
+
+| Arquivo                  | Conteúdo                                  | Comitado? |
+| ------------------------ | ----------------------------------------- | --------- |
+| `.env`                   | Segredos da lib externa (API keys, etc.)  | ❌ NUNCA  |
+| `.env.example`           | Mesmas chaves sem valor                   | ✅        |
+| `global.json` ou similar | Defaults globais                          | ✅        |
+| `actualState.json`       | Estado runtime (auto-gerado)              | ❌        |
+| `history/*`              | Logs estruturados                         | ❌        |
+
+Hot-reload de configs (se aplicável): a cada N segundos no loop principal
+(definir `configCacheTime`).
+
+<!-- prod-runner-merge: append section="Convenções de código" -->
+
+### Comportamento do loop após erro (CLI)
+
+O loop principal **NÃO deve morrer silenciosamente**. Erros não
+tratados disparam `console.error` + exit code != 0. Pattern:
+
+```ts
+runTradingLoop({ broker }).catch((error) => {
+  console.error("FATAL: bot loop crashed", error);
+  process.exit(1);
+});
+```
+
+Loop interno tem `try/catch` por par/tarefa pra continuar processando
+outros, mas erro de orquestração mata o processo.
+
+### Observability (CLI)
+
+Status quo recomendado:
+
+- Logs estruturados em `history/*.json` formato Kibana (`_index`,
+  `_source`, `_id`).
+- OpenSearch local via Docker pra dashboards (ou similar).
+- `console.log` apenas pra orquestração (logger estruturado entra
+  em spec dedicada se necessário).

package/profile-cli/code-patterns.md

@@ -0,0 +1,363 @@
+# Code patterns
+
+Padrões para schemas, tipos, services, broker abstrato,
+erros e persistência neste projeto.
+
+Este documento descreve o **alvo arquitetural**. O código atual
+não está todo nesse formato — chegamos lá pelas specs em `specs/`.
+Quando houver divergência entre este doc e o código, este doc
+ganha; o código é o que está sendo refatorado.
+
+---
+
+## Estrutura de pastas (alvo)
+
+```
+tradeBotRefatoring/
+├── CLAUDE.md
+├── index.ts                     ← entrypoint mínimo (loop fino)
+├── docs/                        ← este e outros docs de referência
+├── specs/                       ← specs por domínio
+├── domain/
+│   ├── broker.ts                ← interface BrokerClient
+│   └── errors.ts                ← TradeError e subclasses
+├── services/
+│   ├── waves/
+│   │   ├── schema.ts            ← WavesHistorySchema, derivados
+│   │   ├── waves-history.ts     ← classe / lógica de detecção
+│   │   └── tendency.ts          ← cálculos de tendência
+│   ├── trading/
+│   │   ├── schema.ts            ← TradingDataSchema, BuyOrder, SellOrder
+│   │   ├── limits.ts            ← recalculateLimits puro
+│   │   ├── decisions.ts         ← canBuy / canSell
+│   │   └── loop.ts              ← orquestração do loop
+│   ├── persistence/
+│   │   ├── schema.ts            ← BotStateSchema (root do estado)
+│   │   ├── load.ts              ← reconstrução com schema
+│   │   ├── save.ts              ← serialização
+│   │   └── kibana.ts            ← mapper toKibana
+│   └── integrations/
+│       └── binance-broker.ts    ← adapter @binance/connector → BrokerClient
+└── tests/                       ← Vitest (a partir de setup/01)
+```
+
+---
+
+## Schemas e tipos
+
+### Entity raiz
+
+Cada domínio tem `schema.ts` com a entity Zod. Tipos derivam
+sempre via `z.infer`.
+
+```ts
+// services/trading/schema.ts
+import { z } from "zod";
+
+export const TradingDataSchema = z.object({
+    tradeSymbol: z.string(),
+    totalToBuy: z.number().nonnegative(),
+    sliceToBuy: z.number().positive(),
+    currentSliceToBuy: z.number().positive(),
+    buyOrdersWhithoutStack: z.number().int().nonnegative(),
+    lastTurnDateTime: z.coerce.date().nullable(),
+    lastMaxPrice: z.number().nullable(),
+    lastMinPrice: z.number().nullable(),
+    smallerBuyNotSelledPrice: z.number().nullable(),
+    lastCheckedPrice: z.number().nullable(),
+    maxLimitPriceToBuy: z.number().nullable(),
+    maxLimitPriceToBuy_calc: z.string().nullable(),
+    minLimitPriceToSell: z.number().nullable(),
+    brokeUpFlowWaitingLimitPrice: z.number().nullable(),
+    brokeDownFlowWaitingLimitPrice: z.number().nullable(),
+});
+
+export type TradingData = z.infer<typeof TradingDataSchema>;
+```
+
+### Regras
+
+- Naming: `XxxSchema` pra Zod, `Xxx` pra type inferido.
+- Nullable explícito (`.nullable()`), não `.optional()` por engano.
+- Datas no JSON viram `string`; usar `z.coerce.date()` se quiser `Date` em runtime.
+- Sem `interface` ou `type` paralelo ao schema.
+
+### Derivações
+
+```ts
+// Input com subset + override
+export const CreateBuyOrderInput = BuyOrderSchema.pick({ gotPrice: true, quantity: true, tradeSymbol: true }).extend({
+    orderType: z.enum(["LIMIT_MAKER", "MARKET"]),
+});
+
+export type CreateBuyOrderInput = z.infer<typeof CreateBuyOrderInput>;
+
+// Output sem campos internos
+export const BuyOrderOutput = BuyOrderSchema.omit({ binanceOrderId: true }).extend({ ageMs: z.number() });
+```
+
+---
+
+## Validação na fronteira
+
+Toda entrada do mundo externo passa por `safeParse` ou `parse`
+ANTES de chegar na lógica.
+
+### Boot — leitura de config
+
+```ts
+// services/persistence/load.ts
+import { GlobalConfigSchema } from "../trading/schema";
+
+export function loadGlobalConfig(): GlobalConfig {
+    const raw = JSON.parse(fs.readFileSync("global.json", "utf-8"));
+    const result = GlobalConfigSchema.safeParse(raw);
+    if (!result.success) {
+        console.error("FATAL: global.json inválido", result.error.format());
+        process.exit(1);
+    }
+    return result.data;
+}
+```
+
+### Resposta de broker
+
+```ts
+const BinanceTickerResponseSchema = z.object({
+    symbol: z.string(),
+    price: z.string().regex(/^\d+(\.\d+)?$/),
+});
+
+// dentro do BinanceBroker:
+const result = BinanceTickerResponseSchema.parse(response.data);
+return { symbol: result.symbol, priceCents: toCents(result.price) };
+```
+
+### Reload de estado
+
+Substituir `Object.setPrototypeOf` (vindo da spec 00) por
+reconstrução validada (a partir de refactor/05):
+
+```ts
+// services/persistence/load.ts
+export function loadBotState(): BotState | null {
+    if (!fs.existsSync("actualTradeEnviroments.json")) return null;
+    const raw = JSON.parse(fs.readFileSync("actualTradeEnviroments.json", "utf-8"));
+    return BotStateSchema.parse(raw);
+}
+```
+
+---
+
+## Services
+
+### Estrutura de um domínio
+
+```
+services/{domínio}/
+├── schema.ts        ← entity + derivados
+├── {lógica}.ts      ← funções puras
+└── ...
+```
+
+### Regras
+
+- Funções puras quando possível: input → output, sem side-effects.
+- Side-effects (leitura, escrita, log) ficam em arquivos dedicados:
+  `persistence/`, `integrations/`, ou em camada de orquestração.
+- Services podem importar outros services do MESMO nível ou inferiores.
+- Services NUNCA importam `@binance/connector`, `dotenv`, `fs`, `process`.
+- Services NUNCA chamam `console.log`. Logs são responsabilidade
+  do orquestrador (loop) ou de logger estruturado.
+
+### Exemplo: lógica pura
+
+```ts
+// services/trading/limits.ts
+
+export function recalculateLimits(input: {
+    actualPrice: number;
+    waves: WavesSnapshot;
+    quantityOfBuyOrdersNotSelled: number;
+    config: ConfigValues;
+    trade: TradingData;
+}): RecalculatedLimits {
+    // ...lógica determinística, sem ed.log, sem process, sem fs
+    return {
+        maxLimitPriceToBuy,
+        minLimitPriceToSell,
+        brokeUpFlowWaitingLimitPrice,
+        brokeDownFlowWaitingLimitPrice,
+        maxLimitPriceToBuy_calc,
+    };
+}
+```
+
+Função pura é alvo direto de teste unitário: alimentar inputs,
+verificar outputs.
+
+---
+
+## BrokerClient (port)
+
+Interface no domínio. Implementação em `services/integrations/`.
+
+```ts
+// domain/broker.ts
+export interface BrokerClient {
+    getTickerPrice(symbol: string): Promise<{ symbol: string; price: number }>;
+    placeOrder(input: PlaceOrderInput): Promise<PlacedOrder>;
+    getAccountState(): Promise<AccountState>;
+}
+```
+
+```ts
+// services/integrations/binance-broker.ts
+import { Spot } from "@binance/connector";
+
+export class BinanceBroker implements BrokerClient {
+    constructor(
+        private apiKey: string,
+        private apiSecret: string
+    ) {
+        this.client = new Spot(apiKey, apiSecret);
+    }
+    async getTickerPrice(symbol: string) {
+        const { data } = await this.client.tickerPrice(symbol);
+        const parsed = BinanceTickerResponseSchema.parse(data);
+        return { symbol: parsed.symbol, price: Number(parsed.price) };
+    }
+    // ...
+}
+```
+
+### Por quê
+
+- Lógica de trade testável com mock de broker (`InMemoryBroker`).
+- Trocar Binance por outra exchange é trocar 1 arquivo.
+- Validação da resposta vive no adapter, não espalhada.
+
+---
+
+## Erros de domínio
+
+Lógica nunca lança `Error` puro. Usa classe específica.
+
+```ts
+// domain/errors.ts
+export class TradeError extends Error {
+    constructor(
+        message: string,
+        public code: string
+    ) {
+        super(message);
+        this.name = "TradeError";
+    }
+}
+
+export class SafeLimitError extends TradeError {
+    constructor(message: string) {
+        super(message, "SAFE_LIMIT_VIOLATED");
+    }
+}
+
+export class BrokerError extends TradeError {
+    constructor(
+        message: string,
+        public binanceMsg?: string
+    ) {
+        super(message, "BROKER_ERROR");
+    }
+}
+
+export class InvalidConfigError extends TradeError {
+    constructor(message: string) {
+        super(message, "INVALID_CONFIG");
+    }
+}
+```
+
+### Regras
+
+- Mensagens em pt-BR (consistente com logs existentes).
+- `code` em SCREAMING_SNAKE_CASE.
+- Stack trace preservado: `throw error` ou `throw new XxxError(msg, error)` nunca `throw error.message`.
+
+---
+
+## Mapper toKibana
+
+Centralizado em `services/persistence/kibana.ts`.
+
+```ts
+export function toKibana<T>(record: T, id: string, index = "tradebot"): KibanaRecord<T> {
+    return {
+        _index: index,
+        _type: "_doc",
+        _id: id,
+        _score: 1,
+        _source: record,
+    };
+}
+
+export function toKibanaJsonl<T>(records: Array<{ data: T; id: string }>): string {
+    return records.map(({ data, id }) => JSON.stringify(toKibana(data, id))).join("\n") + "\n";
+}
+```
+
+Substitui o `formatDocumentToKibana` espalhado no `index.ts` atual.
+
+---
+
+## Persistência
+
+### Save
+
+```ts
+// services/persistence/save.ts
+export function saveBotState(state: BotState) {
+    const validated = BotStateSchema.parse(state);
+    fs.writeFileSync("actualTradeEnviroments.json", JSON.stringify(validated), "utf-8");
+}
+```
+
+Validação em save protege contra escrever estado corrompido
+(útil na transição da spec 00 pra 05).
+
+### Load
+
+Já mostrado em "Validação na fronteira > Reload de estado".
+
+### Substituição do `Object.setPrototypeOf`
+
+Spec 00 deixou `Object.setPrototypeOf(item, BotEnviromentData.prototype)`
+como solução temporária. Quando schemas Zod existirem (setup/02),
+refactor/05 substitui por:
+
+```ts
+const state = BotStateSchema.parse(raw);
+// state já é tipado, sem precisar reanexar prototype manualmente
+```
+
+Classes podem virar funções/objetos puros, ou continuar como classes
+com método estático `from(plain): T` que invoca o construtor.
+Decisão fica pra refactor/05.
+
+---
+
+## Convenções de naming
+
+| Item                        | Padrão                     | Exemplo                                 |
+| --------------------------- | -------------------------- | --------------------------------------- |
+| Schema Zod                  | `XxxSchema`                | `TradingDataSchema`                     |
+| Type inferido               | `Xxx`                      | `TradingData`                           |
+| Funções                     | `camelCase` verbo + objeto | `recalculateLimits`, `loadBotState`     |
+| Classes (quando inevitável) | `PascalCase` substantivo   | `BinanceBroker`, `WavesHistory`         |
+| Arquivos                    | `kebab-case.ts`            | `binance-broker.ts`, `waves-history.ts` |
+| Constantes                  | `SCREAMING_SNAKE_CASE`     | `DEFAULT_TIMER_MS`                      |
+| Erro                        | `XxxError`                 | `SafeLimitError`                        |
+| Test files                  | `xxx.test.ts`              | `waves-history.test.ts`                 |
+
+Exceção: arquivos do código atual (`BotEnviromentData.ts`, etc.) ficam
+como estão até serem refatorados em suas specs respectivas. Nada de
+renomeação fora do escopo da spec corrente.