Guia de Migracion RaiSE 3.1: venv per-project a Binario Global¶

Audiencia: Cualquier usuario con una instalacion previa de RaiSE (venv per-project, pipx, pip --user, o el antiguo install.sh) que aun no tiene el binario global.

Tiempo estimado: 5--15 minutos por checkout de proyecto.

Todos los comandos de abajo se pueden copiar y pegar directamente.

1. Para quien es esto -- como saber que instalacion tienes¶

Ejecuta which rai (Linux/macOS) o Get-Command rai (Windows PowerShell) y compara la salida:

Salida de `which rai`	Metodo de instalacion	Accion
`.venv/bin/rai` o `.venv\Scripts\rai.exe`	Venv per-project (script de instalacion o manual)	Sigue esta guia
`~/.local/pipx/venvs/raise-cli/bin/rai`	pipx	Sigue esta guia
`~/.local/bin/rai` (symlink a un sitio pip --user)	pip --user	Sigue esta guia
`~/.local/bin/rai` (symlink a `~/.local/share/rai/`)	Binario global -- ya migrado	Salta al Paso 3
Sin salida / "not found"	No instalado	Ve al Paso 1

Si no estas seguro, revisa el destino: ls -l $(which rai). Un symlink que apunta a ~/.local/share/rai/ es el binario global. Cualquier otra cosa es una instalacion anterior.

2. Paso 1 -- Instalar el binario global¶

Linux / macOS¶

curl -fsSL https://github.com/humansys/raise/releases/latest/download/install.sh | bash

Windows (PowerShell)¶

irm https://github.com/humansys/raise/releases/latest/download/install.ps1 | iex

Descargar e inspeccionar primero¶

Si prefieres revisar antes de ejecutar:

curl -fsSL -o /tmp/rai-install.sh https://github.com/humansys/raise/releases/latest/download/install.sh
less /tmp/rai-install.sh
bash /tmp/rai-install.sh

Fijar una version especifica¶

curl -fsSL https://github.com/humansys/raise/releases/latest/download/install.sh | bash -s -- --version v3.1.0

./install.ps1 -Version v3.1.0

ADVERTENCIA: NO uses docs.raiseframework.ai/install.sh para actualizar.

La URL https://docs.raiseframework.ai/install.sh es el antiguo instalador de venv per-project. Crea un .venv en el directorio de tu proyecto e instala raise-cli desde el registry de pre-release de GitLab. Ejecutarlo "para actualizar" recrea exactamente el residuo que esta migracion elimina.

El nuevo instalador de binario esta en GitHub Releases de humansys/raise: https://github.com/humansys/raise/releases/latest/download/install.sh

Que hace el instalador¶

Descarga binarios precompilados (rai + rai-mcp-pipeline) de GitHub Releases.
Verifica checksums SHA-256 de ambos binarios antes de instalar (atomico).
Instala en ~/.local/share/rai/ (Linux/macOS) o %LOCALAPPDATA%\rai\ (Windows), con symlinks en ~/.local/bin/.
Registra %LOCALAPPDATA%\rai\ en el PATH del usuario (solo Windows).
No requiere Python.

3. Paso 2 -- Verificar que el binario esta activo¶

which rai        # deberia mostrar ~/.local/bin/rai
rai --version    # deberia mostrar la version instalada

En Windows:

Get-Command rai
rai --version

Si which rai todavia muestra .venv/bin/rai o una ruta de pipx, el antiguo punto de entrada esta ocultando al binario. Consulta PATH shadowing en la seccion de troubleshooting mas abajo.

Solucion rapida:

hash -r                       # limpiar la cache de comandos de bash
export PATH="$HOME/.local/bin:$PATH"  # asegurar que el directorio del binario va primero

4. Paso 3 -- Escanear y limpiar¶

Este es el nucleo de la migracion. Tienes dos opciones:

Automatico (recomendado): rai clean --force se encarga de todo -- venvs, bases de datos huerfanas, configs obsoletos. No necesitas desinstalar manualmente.
Control manual: si prefieres revisar y eliminar las cosas tu mismo, consulta el Apendice A para los comandos de desinstalacion por metodo, y despues vuelve aqui para ejecutar rai clean con el resto.

Previsualizar que va a pasar¶

cd ~/projects/my-app
rai clean --dry-run

Ejemplo de salida (sanitizada):

Legacy install scan -- 12 residue(s) found

                          ACTIONS (will be processed)
+----------------------------+---------------------+-------------+
| path                       | kind                | action      |
+----------------------------+---------------------+-------------+
| .raise/rai/raise.db        | orphan-db           | consolidate |
| .mcp.json                  | stale-mcp-command   | fix-config  |
| .codex/config.toml         | stale-runtime-config| fix-config  |
+----------------------------+---------------------+-------------+

                        ADVISORY (manual action needed)
+----------------------------+---------------------+-------------------+
| path                       | kind                | hint              |
+----------------------------+---------------------+-------------------+
| .venv                      | venv-raise-cli      | delete or move    |
| requirements.txt           | requirements-dep    | remove raise-cli  |
| pyproject.toml             | pyproject-dep       | remove raise-cli  |
| uv.lock                    | uvlock-entry        | re-lock           |
+----------------------------+---------------------+-------------------+

Dry run -- nothing was changed.
Run rai clean to process owned residues.
Run rai clean --force to process ALL residues (including advisory).

ACTIONS son residuos que rai clean gestiona y procesara automaticamente (bases de datos huerfanas, claves de config obsoletas). Es seguro procesarlos sin revision manual.

ADVISORY son residuos en archivos que tu controlas (venvs, pyproject.toml, uv.lock) -- rai clean los lista pero no los toca a menos que pases --force.

Limpiar todo¶

rai clean --force

Esto procesa ACTIONS (residuos gestionados) y ADVISORY (venvs, referencias de dependencias) con un prompt de confirmacion. Revisa el plan y escribe yes para continuar.

Sobre los venvs: rai clean --force elimina venvs que contienen raise-cli. Si un venv tambien tiene las dependencias propias de tu proyecto, rai clean te avisara -- en ese caso elimina raise-cli manualmente (consulta el Apendice A).

Que significa "consolidate" para bases de datos huerfanas: si rai clean encuentra un .raise/rai/raise.db local del proyecto, sus datos se fusionan en el ~/.rai/raise.db global. Tras una fusion exitosa, el archivo local se renombra a raise.db.consolidated (nunca se elimina). Puedes eliminar los archivos .consolidated de forma segura una vez que hayas verificado la migracion.

Reparar configs¶

rai clean --fix-config

Esto repara archivos de configuracion que referencian rutas antiguas (por ejemplo, entradas de .mcp.json que apuntan a .venv/bin/rai-mcp-pipeline en lugar del binario global).

Si .mcp.json esta trackeado en git, --fix-config aplica la reparacion de todas formas: escribe un backup .bak y deja el diff en tu working tree para que lo revises y hagas commit.

Antes de continuar, resuelve los residuos pyproject-dep y uvlock-entry listados en Residuos que necesitan accion manual -- rai upgrade en el siguiente paso asume un proyecto limpio.

5. Paso 4 -- Actualizar el scaffold del proyecto¶

Ejecuta rai upgrade --detect para poner al dia el scaffold .raise/ de tu proyecto y volver a detectar los agentes instalados:

rai upgrade --detect

Prefiere upgrade sobre rai init --force. upgrade --detect preserva tu manifest, la documentacion de gobernanza y las skills personalizadas, y no escribe entradas huerfanas en ~/.rai/developer.yaml (un problema conocido de init --force). Reserva rai init --force --detect para un checkout que nunca fue inicializado (sin directorio .raise/).

6. Paso 5 -- Importar datos legacy¶

Las sesiones, entradas de journal, signals, pipeline runs y patterns antiguos viven en archivos planos (JSONL/JSON/YAML) o en un esquema SQLite anterior. Importalos a la base de datos actual explicitamente -- nada dispara esto automaticamente durante upgrade o init --force:

rai db import-legacy

Esto es idempotente: los archivos originales se renombran a *.migrated, nunca se eliminan, asi que es seguro ejecutarlo mas de una vez. Aunque rai db import-legacy --help solo lista sesiones, entradas de journal, signals y pipeline runs, tambien migra tus patterns por completo.

Segun la version desde la que estas migrando:

Version de origen	Que esperar
2.x (JSONL)	Obligatorio. `patterns.jsonl` no se auto-migra -- si te saltas este paso, pierdes tus patterns silenciosamente.
3.0.0 (SQLite v24)	Puede imprimir un traceback de `IntegrityError` de la migracion de slugs. Es cosmetico -- la migracion se completa y los datos quedan intactos. Seguro de ignorar.
3.1.0 pre-releases (SQLite v50+)	Tipicamente imprime "Nothing to migrate" -- esperado, tus datos ya estaban en SQLite.

Verifica la importacion:

rai db status

Para el contexto de por que cambio este almacenamiento, consulta BC3 -- SQLite reemplaza el almacenamiento JSONL/JSON en la guia de migracion de 2.x.

7. Paso 6 -- Reconstruir el knowledge graph¶

El knowledge graph es estado derivado -- reconstruyelo despues de una migracion de esquema o de datos:

rai graph build

La granularidad de los simbolos puede diferir un poco de builds anteriores (cambios en el scanner entre versiones); eso no es perdida de datos.

8. Paso 7 -- Verificar¶

rai doctor                    # diagnostico completo
rai doctor -c legacy          # solo checks de legacy

Luego ejecuta una prueba rapida:

rai session start my-test --project .

Por ultimo, confirma que no quedan residuos:

rai clean --dry-run    # espera cero residuos

Repite los pasos 3--7 para cada checkout y worktree de proyecto en tu maquina. Cada checkout puede tener sus propios residuos (venvs, bases de datos locales, archivos de config). Los pasos 1--2 y 8 son per-machine, se hacen una sola vez.

9. Paso 8 -- Limpiar `~/.rai/developer.yaml`¶

Esto es una limpieza per-machine, unica vez -- no un paso por checkout.

rai init escribe en el ~/.rai/developer.yaml global real sin importar que entorno lo disparo (un problema conocido), asi que las entradas huerfanas pueden acumularse entre corridas de prueba y checkouts eliminados. rai doctor y rai clean ahora las detectan automaticamente:

rai doctor -c developer-yaml    # reporta entradas de proyecto huerfanas y sesiones stale
rai clean --dry-run              # las lista junto con otros residuos
rai clean                        # poda las entradas huerfanas (escribe developer.yaml.bak primero)

Que se detecta:

entradas de projects: que apuntan a rutas que ya no existen en disco.
entradas de active_sessions: con mas de 48 horas de antiguedad y sin directorio de estado de sesion correspondiente.

Las entradas validas nunca se tocan. Se escribe un backup del archivo original en developer.yaml.bak antes de cualquier modificacion.

10. Residuos que necesitan accion manual¶

Despues de rai clean --force, algunos residuos pueden quedar porque requieren una decision. Esto es lo que significa cada tipo y que hacer:

Tipo	Donde	Que hacer
`requirements-dep`	`requirements.txt` o similar	Elimina la linea de `raise-cli` / `raise-core`. Ya no se instalan via pip.
`pyproject-dep`	`pyproject.toml` `[project.dependencies]`	Elimina `raise-cli` / `raise-core` de la lista de dependencias.
`uvlock-entry`	`uv.lock`	Despues de eliminar la dependencia del pyproject, ejecuta `uv lock` para regenerar.
`repo-cartridge-self-ingest`	`.raise/cartridges/repo/instances/repo.json`	El antiguo repo cartridge se reingesta en el proximo graph build, causando un `RepoCartridgeCollapseError`. Mueve el directorio `instances/` aparte: `mv .raise/cartridges/repo/instances /tmp/repo-instances-bak && rai graph build`

Si rai clean --dry-run muestra cero items ADVISORY despues de resolver estos, tu checkout esta completamente migrado.

Apendice A -- Desinstalacion manual (cuando `rai clean` no es suficiente)¶

En la mayoria de los casos rai clean --force se encarga de todo. Usa la desinstalacion manual solo cuando el venv esta compartido con las dependencias propias de tu proyecto y no se puede eliminar por completo.

Venv per-project (mas comun)¶

cd ~/projects/my-app
rm -rf .venv

ADVERTENCIA: Elimina el venv, nunca lo renombres.

Aunque la version final de 3.1.0 ahora excluye patrones renombrados comunes (.venv.old, .venv-backup), las versiones anteriores no lo hacian. En un reporte de campo en rc3, un venv renombrado produjo 89,589 nodos basura (97% del grafo) y un repo.json trackeado de 62 MB. Eliminar es el enfoque mas seguro independientemente de la version.

Si necesitas conservar los paquetes como referencia, copia la salida de pip freeze a un archivo fuera del arbol del proyecto, y luego elimina el venv.