DOC-011: Local Development Guide
Estado
Accepted — 2026-08-23 (scaffolding) · Enmienda CLI 2026-09-08 (apps/cli + make cli*).
Entrada rápida — CLI (ahora)
Agentes y Codex
make sync-agents genera las superficies de Cursor, Copilot, OpenCode, Claude, Gemini y Codex. Desde Codex, usar make sync-agents FROM=codex después de editar skills/comandos/reglas y make test-agent-sync para verificar el sync en repos temporales. Guía Codex · metodología compartida. Si doctor no encuentra CLIs ya instaladas desde desktop, recuperar el PATH según DOC-014.
Motor Python en apps/cli/. No requiere Nest/Next.
make doctor
make cli-install # apps/cli/.venv + requirements.txt
make cli ARGS='AAPL' # análisis
make cli ARGS='AAPL --opciones'
make cli-smoke # necesita red (Yahoo)
make cli-test # unit tests sin red
# Tests opcionales: workflow manual de GitHub (ver abajo)
Guía del kit: apps/cli/README.md. Shims en raíz: python main.py … reenvía a apps/cli.
Entrada rápida — SaaS (diferido)
Scaffold Nest/Next aún no — spike SaaS producto GO pendiente (DOC-020). Cuando exista:
make install # pnpm + prisma generate
make infra-up # Postgres + Redis + Mailpit
cp .env.example .env # native pnpm dev
# Sin checks automáticos; ver workflow manual de tests abajo.
pnpm dev # API :3000 · Web :3001 · Help :3002 · Docs :3003
# or
make local-up # same stack inside Docker (profile dev)
| Superficie | URL |
|---|---|
| API | http://localhost:3000 |
| Health | http://localhost:3000/health/live |
| Web | http://localhost:3001 |
| Help Center | http://localhost:3002 |
| Developer Docs | http://localhost:3003/en · http://localhost:3003/es |
| Mailpit | http://localhost:8025 |
| Grafana (ops) | http://localhost:3004 — make observability-up |
| Scanner engine | http://localhost:8090/health — CLI via Compose (make local-up) |
| Prometheus | http://localhost:9090 |
| Loki | http://localhost:3110 |
Observability (opcional): ver docs/ops/go-live/observability-stack.md. Antes de producción: proyectos GTM/Clarity/Grafana propios de IVPrior — pre-prod-analytics-projects.md.
Staff local: after make local-db-migrate and make local-db-seed (or pnpm --filter @ivprior/api db:migrate / db:seed on the host), sign in at http://localhost:3001/platform/login with alex@ivprior.local / Alex1234! when PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD are set (see DOC-016). The seed publishes Lite/Plus/Premium, public social links, IAM, and a demo subscriber at /t/demo (owner@demo.local / Demo1234!). Subscriber directory: http://localhost:3001/platform/subscribers. Docker dev still runs platform:seed-admin + platform:seed-iam on API start if you skip full db:seed.
Compose: devops/docker/ (wrapper ./devops/docker/compose). Env Docker: copy .env.docker.example → .env.docker (make infra-up lo copia).
Tests manuales y cierre rápido
Desde 2026-09-13 no se ejecutan tests, lint, typecheck ni builds automáticamente en el PC, al abrir PR o al cerrar sesión. make ship hace push → PR → merge → sync master sin lanzar ni esperar comprobaciones.
El workflow Manual tests (.github/workflows/manual-tests.yml) solo tiene workflow_dispatch. Una vez integrado en master, puede lanzarse desde Actions → Manual tests → Run workflow, o bajo petición expresa:
gh workflow run manual-tests.yml --ref master -f suite=all
all ejecuta tests del monorepo (incluidos HTTP API), CLI Python, sincronización de agentes y Playwright de schedules/Today. unit omite navegador; browser ejecuta únicamente esas dos suites de navegador. No se ejecutan build de producción, lint ni typecheck. API y Web arrancan en modo desarrollo en el runner para Playwright; los datos demo y PostgreSQL/Redis son efímeros. Los reportes de navegador se conservan siete días.
El cierre solo propone el comando; no lo ejecuta. Para probar una rama usar --ref nombre-de-rama. El workflow debe existir primero en la rama por defecto. Los resultados no bloquean merge.
Referencia: ejecución manual de workflows (GitHub).
Husky conserva un pre-commit informativo y un pre-push que prohíbe push directo a master/main, ambos sin comprobaciones de código. Los targets make check, make test y otros siguen disponibles para pedidos explícitos; no deben inferirse como tarea automática del agente.