tai-sql 0.7.11__tar.gz → 0.7.12__tar.gz

{tai_sql-0.7.11 → tai_sql-0.7.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tai-sql
-Version: 0.7.11
+Version: 0.7.12
 Summary: SQL database management and code generation tool
 License-Expression: MIT
 License-File: LICENSE

{tai_sql-0.7.11 → tai_sql-0.7.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tai-sql"
-version = "0.7.11"
+version = "0.7.12"
 description = "SQL database management and code generation tool"
 license = "MIT"
 license-files = ["LICENSE"]

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/cli/commands/cmd_pull/funcs.py

@@ -14,11 +14,12 @@ from __future__ import annotations
 
 import os
 import tempfile
+from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional, Sequence
+from typing import Iterator, Optional, Protocol, Sequence
 
-from sqlalchemy import inspect
+from sqlalchemy import Engine, event, inspect
 
 from tai_sql.connection import Provider
 from tai_sql.errors import ErrorCode, ProjectError, TaiSqlError
@@ -47,6 +48,52 @@ class PullResult:
     load_errors: tuple[str, ...] = ()
 
 
+class PullProgress(Protocol):
+    """
+    Lo que `run_pull` cuenta mientras trabaja, para quien quiera enseñarlo.
+
+    Leer el catálogo de una base de datos grande —y más detrás de un túnel— tarda: un
+    `pull` de cien tablas puede pasar un minuto sin escribir nada, y eso no se distingue de
+    uno colgado. El flujo anuncia en qué fase está y cada consulta que lanza; pintarlo es
+    cosa de la capa de presentación.
+    """
+
+    def step(self, message: str) -> None:
+        """Empieza una fase: 'Leyendo tablas…'."""
+
+    def query(self) -> None:
+        """Se ha lanzado una consulta contra la base de datos."""
+
+
+class _Silent:
+    """El progreso que no se enseña: lo que recibe `run_pull` si nadie pide otro."""
+
+    def step(self, message: str) -> None:
+        pass
+
+    def query(self) -> None:
+        pass
+
+
+@contextmanager
+def _counting_queries(engine: Engine, progress: PullProgress) -> Iterator[None]:
+    """
+    Avisa al progreso de cada consulta que se lanza contra `engine` mientras dura.
+
+    Es la única señal de vida que da la reflexión: `MetaData.reflect` es una sola llamada
+    que no dice por qué tabla va. El `Engine` se cachea por provider, así que el listener
+    se retira al salir: no puede quedarse contando para el siguiente consumidor.
+    """
+    def _on_query(*_args, **_kwargs) -> None:
+        progress.query()
+
+    event.listen(engine, 'before_cursor_execute', _on_query)
+    try:
+        yield
+    finally:
+        event.remove(engine, 'before_cursor_execute', _on_query)
+
+
 def resolve_provider(source: str) -> Provider:
     """
     El proveedor de conexión, a partir de lo que se pasó en `-p/--provider`.
@@ -114,6 +161,7 @@ def run_pull(
     exclude: Sequence[str] = (),
     force: bool = False,
     to_stdout: bool = False,
+    progress: Optional[PullProgress] = None,
 ) -> PullResult:
     """
     Construye el fichero de schema que describe una base de datos.
@@ -128,6 +176,7 @@ def run_pull(
         exclude: Tablas que no se declaran.
         force: Sobrescribir un fichero de schema existente.
         to_stdout: No escribir nada; devolver el contenido.
+        progress: A quién contarle en qué fase va. Ver `PullProgress`.
 
     Returns:
         El resultado, con el blueprint para poder informar de los descartes.
@@ -158,6 +207,25 @@ def run_pull(
             code=ErrorCode.INVALID_PROVIDER,
         )
 
+    progress = progress or _Silent()
+
+    with _counting_queries(provider.engine, progress):
+        return _pull(
+            pm, provider, driver, progress,
+            source=source, db_schema=db_schema, schema_name=schema_name,
+            env_var=env_var, syntax=syntax, exclude=exclude, force=force,
+            to_stdout=to_stdout,
+        )
+
+
+def _pull(
+    pm, provider: Provider, driver, progress: PullProgress, *,
+    source: str, db_schema: Optional[str], schema_name: Optional[str],
+    env_var: Optional[str], syntax: str, exclude: Sequence[str], force: bool,
+    to_stdout: bool,
+) -> PullResult:
+    """El flujo de `run_pull`, una vez resuelto el origen."""
+    progress.step(f'Conectando con {provider.database or provider.drivername}')
     destino_db = resolve_db_schema(provider, db_schema)
     nombre = schema_name or destino_db or 'main'
 
@@ -176,13 +244,18 @@ def run_pull(
             code=ErrorCode.DUPLICATE_NAME,
         )
 
+    progress.step(f"Leyendo el catálogo de '{destino_db}'")
     estado, _ = build_remote_state(
         provider.engine, driver, destino_db or None, target=nombre
     )
+
+    if estado.views:
+        progress.step(f'Leyendo {len(estado.views)} vista(s)')
     columnas_vista = read_view_columns(
         provider.engine, driver, destino_db or None, list(estado.views)
     )
 
+    progress.step(f'Deduciendo el schema ({len(estado.tables)} tablas)')
     blueprint = build(
         estado,
         driver,
@@ -195,6 +268,8 @@ def run_pull(
     )
 
     contenido = render(blueprint)
+
+    progress.step('Comprobando que el schema carga')
     errores = self_check(blueprint, provider)
 
     if to_stdout:
@@ -215,6 +290,7 @@ def run_pull(
             code=ErrorCode.SCHEMA_IMPORT_FAILED,
         )
 
+    progress.step('Escribiendo el schema')
     escritas = _write(pm, blueprint, contenido, fichero)
 
     return PullResult(
@@ -336,4 +412,4 @@ def _write(pm, blueprint: SchemaBlueprint, contenido: str, fichero: Path) -> tup
     return _write_views(pm.paths.views_dir, blueprint)
 
 
-__all__ = ['PullResult', 'run_pull', 'resolve_provider', 'resolve_db_schema', 'self_check']
+__all__ = ['PullProgress', 'PullResult', 'run_pull', 'resolve_provider', 'resolve_db_schema', 'self_check']

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/cli/commands/cmd_pull/main.py

@@ -16,6 +16,8 @@ Este módulo es la capa de presentación; el flujo está en `funcs.py`.
 from __future__ import annotations
 
 import sys
+from contextlib import contextmanager
+from typing import Iterator, Optional
 
 import click
 
@@ -61,16 +63,18 @@ from .funcs import run_pull
 def pull(provider, db_schema, schema_name, env_var, syntax, exclude, to_stdout, force):
     """Construye el schema a partir de una base de datos existente"""
 
-    resultado = run_pull(
-        source=provider,
-        db_schema=db_schema,
-        schema_name=schema_name,
-        env_var=env_var,
-        syntax=syntax,
-        exclude=exclude,
-        force=force,
-        to_stdout=to_stdout,
-    )
+    with _progress() as progreso:
+        resultado = run_pull(
+            source=provider,
+            db_schema=db_schema,
+            schema_name=schema_name,
+            env_var=env_var,
+            syntax=syntax,
+            exclude=exclude,
+            force=force,
+            to_stdout=to_stdout,
+            progress=progreso,
+        )
 
     if to_stdout:
         # El schema por stdout y el informe por stderr: así se puede canalizar el fichero
@@ -99,6 +103,60 @@ def pull(provider, db_schema, schema_name, env_var, syntax, exclude, to_stdout,
     )
 
 
+class _Spinner:
+    """
+    El progreso de `pull` en una línea que se reescribe: fase, consultas y tiempo.
+
+    El contador de consultas es la señal de vida. La reflexión es una sola llamada que no
+    dice por qué tabla va; que el número suba es lo que distingue un `pull` que trabaja de
+    uno colgado. Va por stderr, igual que el informe, para no mezclarse con `--stdout`.
+    """
+
+    def __init__(self, progress) -> None:
+        self._progress = progress
+        self._task = progress.add_task('Preparando…', total=None, queries=0)
+        self._queries = 0
+
+    def step(self, message: str) -> None:
+        self._progress.update(self._task, description=f'{message}…')
+
+    def query(self) -> None:
+        self._queries += 1
+        self._progress.update(self._task, queries=self._queries)
+
+
+@contextmanager
+def _progress() -> Iterator[Optional[_Spinner]]:
+    """
+    El spinner, solo si stderr es un terminal.
+
+    En un script o en CI no hay nadie mirando, y una línea que se reescribe acaba en el log
+    como basura. Sin terminal, `run_pull` recibe `None` y no cuenta nada. `transient` borra
+    la línea al terminar: lo que queda en pantalla es el resultado, no el andamiaje.
+
+    Se pregunta a `isatty()` y no a `Console.is_terminal`, que con `FORCE_COLOR` dice que sí
+    a cualquier salida: poder pintar colores no significa que haya alguien mirando.
+    """
+    if not sys.stderr.isatty():
+        yield None
+        return
+
+    from rich.console import Console
+    from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+
+    consola = Console(file=sys.stderr)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn('{task.description}'),
+        TextColumn('[dim]{task.fields[queries]} consultas[/dim]'),
+        TimeElapsedColumn(),
+        console=consola,
+        transient=True,
+    ) as progress:
+        yield _Spinner(progress)
+
+
 def _resumen(blueprint: SchemaBlueprint) -> None:
     """Qué se ha reconstruido, en una línea por tipo de objeto."""
     click.echo(

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/cli/commands/cmd_rules/main.py

@@ -19,7 +19,14 @@ from typing import Optional, Sequence
 
 import click
 
-from tai_sql.rules import RuleState, current_version, installer_for, schema_context
+from tai_sql.rules import (
+    RuleState,
+    current_version,
+    installer_for,
+    legacy_rules_dir,
+    retire_directory,
+    schema_context,
+)
 
 from ...preamble import available_schemas, load_schema, resolve_schema_name
 
@@ -53,7 +60,9 @@ def _contexts(names: Sequence[str]) -> list:
     contextos = []
     for nombre in names:
         manager = load_schema(nombre)
-        contextos.append(schema_context(nombre, manager, pm.paths.root))
+        contextos.append(
+            schema_context(nombre, manager, pm.paths.root, pm.paths.workspace_root)
+        )
     return contextos
 
 
@@ -67,6 +76,44 @@ def _target_dir():
     return pm.paths.platform_rules_dir
 
 
+def _retire_legacy() -> None:
+    """
+    Retira las reglas de la ubicación de antes de la 0.7.12, dentro del proyecto.
+
+    Allí el asistente solo las cargaba al leer un fichero de esa carpeta, y dejarlas
+    tendría dos copias de versiones distintas diciendo cosas distintas.
+    """
+    from tai_sql import pm
+
+    antigua = legacy_rules_dir(pm.paths)
+    if antigua is None:
+        return
+    retirada = retire_directory(antigua, stop=pm.paths.root)
+    for nombre in retirada.removed:
+        click.echo(f"   🗑️  {nombre} (de la ubicación antigua)")
+    if retirada.kept:
+        click.echo()
+        click.echo(
+            f"⚠️  En {antigua} quedan {', '.join(retirada.kept)}, que alguien editó: no se "
+            f"han borrado. Las reglas están ahora en {pm.paths.platform_rules_dir}; "
+            f"borra esa carpeta cuando hayas recuperado lo que necesites."
+        )
+    click.echo()
+
+
+def _legacy_reason() -> str:
+    """Por qué la ubicación antigua desalinea, o cadena vacía si no hay nada allí."""
+    from tai_sql import pm
+
+    antigua = legacy_rules_dir(pm.paths)
+    if antigua is None:
+        return ''
+    return (
+        f"hay reglas en {antigua}, la ubicación de antes de la 0.7.12, que el asistente "
+        f"no carga al arrancar"
+    )
+
+
 @click.group()
 def rules():
     """Gestiona las reglas de contexto para asistentes de IA"""
@@ -96,6 +143,7 @@ def rules_install(schema: Optional[str], force: bool):
     parcial = bool(schema)
     instalador = installer_for(destino, _contexts(nombres), track_orphans=not parcial)
     resultado = instalador.install(force=force)
+    _retire_legacy()
 
     for nombre in resultado.written:
         click.echo(f"   ✅ {nombre}")
@@ -159,11 +207,13 @@ def rules_check(schema: Optional[str]):
         destino, _contexts(nombres), track_orphans=not parcial
     ).inspect()
 
-    if informe.aligned:
+    antigua = _legacy_reason()
+    if informe.aligned and not antigua:
         click.echo(f"✅ Las reglas están al día (tai-sql {informe.version})")
         return
 
-    click.echo(f"❌ Las reglas no están al día: {informe.reason()}")
+    motivo = '; '.join(m for m in (informe.reason(), antigua) if m)
+    click.echo(f"❌ Las reglas no están al día: {motivo}")
     click.echo()
 
     if informe.installed and informe.installed_version:
@@ -208,6 +258,11 @@ def rules_diff(schema: Optional[str]):
         destino, _contexts(nombres), track_orphans=not parcial
     ).inspect()
 
+    antigua = _legacy_reason()
+    if antigua:
+        click.echo(f"ℹ️  Además, {antigua}: 'tai-sql rules install' las retira.")
+        click.echo()
+
     if informe.aligned:
         click.echo(f"✅ No hay diferencias (tai-sql {informe.version})")
         return

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/generators/python_client/templates/base.py.jinja2

@@ -18,6 +18,26 @@ import bcrypt
 class Base(DeclarativeBase):
     pass
 
+
+class TriggerAborted(ValueError):
+    """
+    Un trigger del schema ha detenido la operación con `t.abort(mensaje)`.
+
+    Es una regla de negocio que no se cumple, no un fallo: quien la reciba tiene que poder
+    decírselo al usuario tal cual. `message` es el texto que escribió el trigger, sin prefijo.
+
+    Hereda de `ValueError` porque es lo que se lanzaba antes, y el código que ya la captura
+    así sigue funcionando.
+    """
+
+    #: Para reconocerla sin importar la clase: tai-api atiende a los clientes de varios schemas
+    #: con un solo manejador, y cada uno tiene la suya.
+    tai_trigger_abort = True
+
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(f"Trigger abortado: {message}")
+
 {% if has_encrypted_columns %}
 
 # Configuración de encriptación

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/generators/python_client/templates/domain/dao.py.jinja2

@@ -88,6 +88,9 @@ from {{ import_prefix }}_session import {{ session_manager_var }}
 {% if model.columns | selectattr('hash') | list %}
 from {{ import_prefix }}_base import verify_hash, HASH_DE_RELLENO
 {% endif %}
+{% if model.triggers is defined and (model.triggers['create'] or model.triggers['update'] or model.triggers['delete']) %}
+from {{ import_prefix }}_base import TriggerAborted
+{% endif %}
 {# ── Collect cross-DAO targets (relations + trigger cross-table ops) ── #}
 {% set _cross_dao_targets = [] %}
 {% for rel in model.relations | default([]) %}

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/generators/python_client/templates/facade.py.jinja2

@@ -24,6 +24,7 @@ from .{{ model.tablename }}{{ cross_domain_infix }}.{{ dao_sync_module }} import
 from .{{ model.tablename }}{{ cross_domain_infix }}.{{ dao_async_module }} import {{ model.name }}AsyncDAO
 {% endif %}
 {% endfor %}
+from ._base import TriggerAborted
 from ._shared import (
     AggregationResult,
     AggRow,
@@ -159,6 +160,7 @@ __all__ = [
     'set_username',
     'get_username',
     'username_context',
+    'TriggerAborted',
     'AggregationResult',
     'AggRow',
     'AggRequest',

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/generators/python_client/triggers/transformer.py

@@ -11,7 +11,7 @@ Reescribe el AST de la función del trigger sustituyendo la API declarativa
     t.old                      → old_<tablename>
     self.campo                 → new_<tablename>.campo  (create/update)
     t.log(msg)                 → logger.info("🔔 Trigger: ...")
-    t.abort(msg)               → raise ValueError("Trigger abortado: ...")
+    t.abort(msg)               → raise TriggerAborted(msg)   (un ValueError; ver _base.py)
     t.update(Model, pk, **v)   → {Model}SyncDAO(...).update(...)
 
 Vive aquí y no en el ORM porque conoce los nombres de los artefactos generados
@@ -44,7 +44,7 @@ class TriggerCodeTransformer(ast.NodeTransformer):
     
     Mapeo de métodos:
         t.log(msg)   → logger.info("🔔 Trigger: ...")
-        t.abort(msg) → raise ValueError("Trigger abortado: ...")
+        t.abort(msg) → raise TriggerAborted(msg)
     
     Operaciones cross-table:
         t.update(Model, pk, **values)  → {Model}{Mode}DAO(self.session_manager).update(pk, updated_values={Model}UpdateValues(**values), session=session)
@@ -266,13 +266,16 @@ class TriggerCodeTransformer(ast.NodeTransformer):
             return ast.copy_location(ast.Expr(value=new_call), node)
 
         elif method == 'abort':
+            # Una excepción propia y no un `ValueError` con prefijo: quien la recibe —tai-api,
+            # que la convierte en un 422 BUSINESS_RULE_VIOLATION— tiene que poder distinguir una
+            # regla de negocio de un fallo, y darle al usuario el mensaje que escribió el trigger.
+            # El prefijo lo pone la propia excepción al convertirse en texto.
             msg = call.args[0] if call.args else ast.Constant("")
-            prefixed = self._prepend_to_msg("Trigger abortado: ", msg)
             return ast.copy_location(
                 ast.Raise(
                     exc=ast.Call(
-                        func=ast.Name(id='ValueError', ctx=ast.Load()),
-                        args=[prefixed], keywords=[]
+                        func=ast.Name(id='TriggerAborted', ctx=ast.Load()),
+                        args=[msg], keywords=[]
                     ),
                     cause=None
                 ), node

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/generators/rules/__init__.py

@@ -71,6 +71,10 @@ class SchemaRulesContext:
                     máquina y rompería la comparación de `rules check`.
         root:       Raíz del proyecto, para expresar en relativo las rutas de salida de
                     los generadores. No se renderiza.
+        project_dir: Dónde está el proyecto de tai-sql **dentro del repositorio**
+                    (`database`), o `.` si es la raíz. Las reglas se instalan en la raíz
+                    del repositorio y las rutas de este documento son relativas al
+                    proyecto, así que el asistente necesita saber desde dónde leerlas.
     """
 
     schema: SchemaModel
@@ -79,6 +83,7 @@ class SchemaRulesContext:
     generators: tuple[Any, ...] = ()
     file: Optional[str] = None
     root: Optional[str] = None
+    project_dir: Optional[str] = None
 
 
 # ════════════════════════════════════════════════
@@ -302,6 +307,7 @@ def _schema_context(context: SchemaRulesContext) -> dict:
         'name': schema.name,
         'key': context.key or schema.name,
         'file': context.file or '',
+        'project_dir': context.project_dir or '',
         'syntax': schema.syntax,
         'operative_fields': schema.operative_fields,
         'secret_key_name': schema.secret_key_name,

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/generators/rules/templates/schema.md.jinja2

@@ -20,7 +20,13 @@ otros ficheros de este directorio.
 {% for schema in schemas %}
 ## Schema `{{ schema.key }}`
 
+{% if schema.project_dir and schema.project_dir != '.' %}
+- **Proyecto de tai-sql**: `{{ schema.project_dir }}/` (el `.taisqlproject`). Las rutas de
+  este apartado son relativas a él, y los comandos `tai-sql` se ejecutan desde ahí
 - **Fichero**: `{{ schema.file }}` — es el nombre que toma `--schema`
+{% else %}
+- **Fichero**: `{{ schema.file }}` — es el nombre que toma `--schema`
+{% endif %}
 {% if schema.name != schema.key %}
 - **Nombre en la base de datos**: `{{ schema.name }}` (lo declara `datasource(schema=...)`)
 {% else %}

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/introspect/README.md

@@ -80,6 +80,9 @@ en MySQL, donde vive dentro de la definición de la columna.
   `datasource(schema='mi_bd')`, que es lo que declara cualquier schema de MySQL y el prefijo
   que usa el DDL. Antes se escribía `''`, que acababa en `'public'`, y nada cargaba. El SQL
   de las vistas se escribe **sin** ese prefijo, que el catálogo añade.
+- **Una tabla sin clave primaria no se declara, pero se cuenta.** El análisis la
+  rechaza, así que declararla daba un schema que no cargaba. Tampoco es de tai-sql, y el
+  drift no la elimina (`ownership.is_keyless`).
 - **Lo que es de otra herramienta no se declara, pero se cuenta.** La lista está en
   `sync/ownership.py` (sistemas de migraciones, catálogo de PostGIS), y el drift la usa para
   no eliminarlas nunca. Antes se ocultaban sin avisar y el push las borraba.

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/introspect/build.py

@@ -20,7 +20,7 @@ from typing import Mapping, Optional, Sequence
 from ..drivers import DatabaseDriver
 from ..orm.analysis.column_analyzer import OPERATIVE_FIELDS
 from ..orm.ordering import topological_order
-from ..sync.ownership import FOREIGN_PREFIXES, FOREIGN_TABLES, is_foreign_table
+from ..sync.ownership import FOREIGN_PREFIXES, FOREIGN_TABLES, is_foreign_table, is_keyless
 from ..sync.state import ColumnState, IndexState, SchemaState, TableState
 from ..sync.state.normalize import is_numeric_type
 from . import defaults as dfl
@@ -100,6 +100,21 @@ def build(
             reason='es de otra herramienta (migraciones, extensión): no se declara y push no la toca',
         ))
 
+    # Sin clave primaria no hay tabla que declarar: el análisis la rechaza, y un schema
+    # con ella no cargaría. Tampoco es de tai-sql —no ha podido crearla—, así que el
+    # drift no la elimina: se deja fuera, se cuenta y sobrevive intacta.
+    for fisico in sorted(n for n, s in tablas_estado.items() if is_keyless(s)):
+        descartes.append(Discarded(
+            kind='tabla', location=fisico, detail=f'tabla {fisico}',
+            impact=Impact.IGNORED,
+            reason=(
+                'no tiene clave primaria, que el DSL exige: no se declara y push no la '
+                'toca. Para gestionarla con tai-sql, dale una clave primaria en la base '
+                'de datos y vuelve a ejecutar pull'
+            ),
+        ))
+        del tablas_estado[fisico]
+
     for tabla in sorted(excluidas & set(tablas_estado)):
         descartes.append(Discarded(
             kind='tabla', location=tabla, detail=f'tabla {tabla}',
@@ -108,7 +123,9 @@ def build(
         ))
         del tablas_estado[tabla]
 
-    for tabla in sorted(excluidas - set(tablas_estado) - set(state.tables)):
+    # Por nombre, no por clave: las claves de `state.tables` llevan el schema delante.
+    existentes = {s.name for s in state.tables.values()}
+    for tabla in sorted(excluidas - existentes):
         descartes.append(Discarded(
             kind='tabla', location=tabla, detail=f'tabla {tabla}',
             impact=Impact.IGNORED,

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/project/paths.py

@@ -58,23 +58,54 @@ class ProjectPaths:
         """Ruta del fichero de un schema, exista o no."""
         return self.schemas_dir / f'{schema_name}.py'
 
+    @property
+    def workspace_root(self) -> Path:
+        """
+        La raíz del repositorio que contiene el proyecto: el primer directorio, desde
+        `root` hacia arriba, que tiene un `.git`. Sin repositorio, el propio proyecto.
+
+        Es donde se arranca el asistente, y por eso es donde tienen que estar sus reglas.
+        El proyecto de tai-sql suele ser una carpeta del repositorio (`database/`, junto a
+        `api/` y al frontend), y un asistente **no carga al arrancar** el `.claude/rules/`
+        de una subcarpeta: solo cuando lee un fichero de dentro. Las reglas instaladas en
+        `database/.claude/rules/` no llegaban a quien trabajaba en la API o en el
+        frontend, que es justo quien más las necesita.
+        """
+        inicio = self.root.resolve()
+        for directorio in (inicio, *inicio.parents):
+            # `exists()` y no `is_dir()`: en un worktree o un submódulo `.git` es un fichero.
+            if (directorio / '.git').exists():
+                return directorio
+        return inicio
+
     @property
     def rules_dir(self) -> Path:
-        """Directorio de reglas de contexto del proyecto (`.claude/rules`)."""
-        return self.root / self.RULES_DIR
+        """Directorio de reglas de contexto del repositorio (`<raíz>/.claude/rules`)."""
+        return self.workspace_root / self.RULES_DIR
 
     @property
     def platform_rules_dir(self) -> Path:
         """
         Directorio donde `tai-sql rules install` escribe las reglas de la herramienta.
 
-        Es `.claude/rules/_platform/tai-sql`, y el `_platform/` no es organización: es la
-        frontera entre lo que instala tai-sql —borrable y reinstalable— y lo que escribe
-        el equipo. Sin ella se reproduce el problema del código generado: alguien edita,
-        la siguiente instalación lo pisa, y nadie se entera.
+        Es `<raíz del repositorio>/.claude/rules/_platform/tai-sql`, y el `_platform/` no es
+        organización: es la frontera entre lo que instala tai-sql —borrable y
+        reinstalable— y lo que escribe el equipo. Sin ella se reproduce el problema del
+        código generado: alguien edita, la siguiente instalación lo pisa, y nadie se
+        entera. Ver `workspace_root` para por qué la raíz del repositorio y no el proyecto.
         """
         return self.rules_dir / self.PLATFORM_RULES_DIR
 
+    @property
+    def legacy_platform_rules_dir(self) -> Optional[Path]:
+        """
+        Donde las instalaban las versiones anteriores a la 0.7.12: dentro del proyecto de
+        tai-sql. `None` si coincide con la ubicación actual —el proyecto es la raíz del
+        repositorio— y no hay nada que retirar.
+        """
+        antigua = self.root.resolve() / self.RULES_DIR / self.PLATFORM_RULES_DIR
+        return None if antigua == self.platform_rules_dir else antigua
+
     # ── Descubrimiento ───────────────────────────────────────────────────
 
     def discover_schemas(self) -> List[str]:

{tai_sql-0.7.11 → tai_sql-0.7.12}/tai_sql/rules/README.md

@@ -37,7 +37,7 @@ texto, que es la forma preferente de añadir cobertura aquí.
 ## Dónde se instalan, y por qué ahí
 
 ```
-.claude/rules/
+<raíz del repositorio>/.claude/rules/
 ├── _platform/            instalado — NO se edita, es borrable y reinstalable
 │   └── tai-sql/
 │       ├── _meta.json
@@ -52,6 +52,24 @@ La separación física de `_platform/` es un requisito y no organización: sin e
 reproduce el problema que ya tiene el código generado — alguien edita, la siguiente
 instalación lo pisa, y nadie se entera.
 
+**En la raíz del repositorio, no en el proyecto de tai-sql** (`ProjectPaths.workspace_root`:
+el primer directorio hacia arriba con `.git`; sin repositorio, el proyecto). El proyecto suele
+ser una carpeta —`database/`, junto a `api/` y al frontend—, y el asistente carga al arrancar el
+`.claude/rules/` de la raíz pero el de una subcarpeta **solo cuando lee un fichero de dentro**
+(comprobado con Claude Code 2.1). Hasta la 0.7.11 se instalaban en el proyecto, y quien
+trabajaba en la API no las veía. `rules install` retira lo que quede allí con
+`retire_directory()`, que borra lo intacto y deja lo editado; `check` y el aviso de `push` lo
+señalan mientras quede algo. El documento derivado dice dónde está el proyecto dentro del
+repositorio, porque sus rutas son relativas a él.
+
+## Reutilizarlo desde otra librería
+
+`RulesInstaller` no sabe de schemas, y tampoco de quién es: `tool='tai-api'` hace que la
+cabecera diga `<!-- tai-api <versión> · … · regenerar: tai-api rules install -->` y que la
+lectura reconozca esa cabecera y no la de tai-sql. Es lo que usa tai-api para instalar las suyas
+en `_platform/tai-api/`, junto a estas. Lo que le toca a la otra librería: sus documentos, su
+directorio, su versión y su aviso.
+
 **Un fichero derivado por schema**, y no uno por proyecto. Lo que describe un schema no
 tiene que ver con lo que describe otro, y separarlos permite dos cosas: que `push` avise de
 que se quedó obsoleto **el del schema que acaba de tocar** sin cargar los demás, y que