---
name: phantasos-setup
description: >
  Phantasos Setup — instalación y primeros pasos.
  Trigger: Cuando el usuario quiere instalar phantasos, iniciar un proyecto con phantasos,
  configurarlo por primera vez, o no sabe por dónde empezar.
license: MIT
metadata:
  author: javier-solis
  version: "1.0"
---

## When to Use

- El usuario no tiene phantasos en su proyecto y quiere instalarlo
- El usuario pregunta "cómo empiezo?" o "primeros pasos"
- El usuario creó un proyecto desde cero y quiere agregar phantasos
- El usuario tiene dudas sobre la configuración inicial

## Qué relevar del usuario ANTES de instalar

Siempre preguntá antes de instalar:

1. **Tipo de instalación**: ¿Querés instalarlo como dependencia de un proyecto existente o querés crear un proyecto nuevo desde cero?
2. **Proyecto nuevo o existente**: Si es existente, ¿dónde está el proyecto? Si es nuevo, ¿en qué carpeta lo creamos?
3. **Modo de instalación**: Como dependencia real de npm (`npm install phantasos`) o como paquete local para desarrollo?
4. **Backend real**: ¿Tenés una API real a la que hacer proxy cuando no hay mock activo? Si sí, ¿cuál es la URL?

## Instalación

### Opción 1: Proyecto nuevo desde cero

```bash
mkdir mi-proyecto
cd mi-proyecto
npm init -y
npm install phantasos --save-dev
mkdir mocks
```

### Opción 2: Proyecto existente

```bash
cd /ruta/a/mi-proyecto
npm install phantasos --save-dev
```

### Opción 3: Desarrollo local (paquete en carpeta local)

```bash
# Build + pack
cd /ruta/a/phantasos
npm run build
npm pack                              # → phantasos-1.0.0.tgz

# Instalar en proyecto de prueba
cd /ruta/a/mi-proyecto
npm install /ruta/a/phantasos-1.0.0.tgz --save-dev
```

Para actualizar después de cambios en phantasos:
```bash
cd /ruta/a/phantasos
npm run build && npm pack

cd /ruta/a/mi-proyecto
npm install /ruta/a/phantasos-1.0.0.tgz --save-dev
```

## Verificar instalación

```bash
npx phantasos --help
# o si está en node_modules/.bin:
phantasos --help
```

Debe mostrar la lista de comandos: `start`, `tree`, `activate`, `deactivate`, `logs`, `new`, `import`, `check`.

## Primer mock

### 1. Crear archivo

```typescript
// mocks/ejemplo/health.ts
import { defineMock } from 'phantasos'

export default defineMock({
  match: ({ req }) =>
    req.method === 'GET' &&
    req.path === '/api/v1/health',

  pre: () => ({
    status: 200,
    body: { status: 'ok', version: '1.0.0' },
  }),
})
```

### 2. Arrancar

```bash
phantasos start
```

### 3. Activar y probar

```bash
# Activar
curl -X POST http://localhost:3001/mock/active/mock/ejemplo/health

# Probar
curl http://localhost:3001/api/v1/health
# → {"status":"ok","version":"1.0.0"}

# Ver árbol
curl http://localhost:3001/mock/tree
```

## Proxy al backend real (opcional)

Si el proyecto tiene una API real, configurarla como variable de entorno.

```bash
REAL_API_URL=https://api.mi-backend.com phantasos start

# O en .env
echo "REAL_API_URL=https://api.mi-backend.com" >> .env
```

Cuando no hay mock activo o el `match()` no da true, el server reenvía al backend real.

## Estructura recomendada de proyecto

```
mi-proyecto/
├── mocks/
│   ├── ordenes/
│   │   ├── crear-orden.ts
│   │   └── cancelar-orden.ts
│   ├── home/
│   │   └── favoritos.ts
│   ├── ws/
│   │   └── cotizaciones.ts
│   └── data/
│       └── orden-base.json
├── src/
│   └── ...
├── package.json
└── .env
```

## Scripts recomendados en package.json

```json
{
  "scripts": {
    "mock": "phantasos start",
    "mock:proxy": "REAL_API_URL=https://api.ejemplo.com phantasos start",
    "mock:tree": "phantasos tree",
    "mock:check": "phantasos check"
  }
}
```

## Troubleshooting de instalación

### "command not found: phantasos"
- ¿Ejecutaste `npm install phantasos`?
- Probá con `npx phantasos` en lugar de `phantasos`
- Revisá que `node_modules/.bin/phantasos` exista

### "Cannot find module 'phantasos'"
- ¿Instalaste phantasos como dependencia? (`npm install phantasos`)
- Si es instalación local: ¿hiciste `npm pack` y `npm install <tgz>`?
- Si usás `npm link`: ¿hiciste `npm link` en phantasos/ y `npm link phantasos` en el proyecto?

### Error al importar mock: "ERR_MODULE_NOT_FOUND"
- El mock importa de `'phantasos'` — necesitás tener phantasos instalado como dependencia
- Si estás en desarrollo local, usá `npm link` o install desde tgz

### "Port 3001 already in use"
- Usá `phantasos start --port 4000` para cambiar el puerto
- O matá el proceso que está usando el puerto