feat(shell): auto-commit con 31 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

python/functions/infra/pg_apply_sql.md

@@ -0,0 +1,59 @@
+---
+name: pg_apply_sql
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "def pg_apply_sql(dsn: str, sql_path: str) -> int"
+description: "Lee un archivo .sql y ejecuta su contenido completo contra PostgreSQL en un solo cursor.execute via psycopg2. Multi-statement en una transaccion (sin parametros). Pensado para migraciones idempotentes (el SQL usa IF NOT EXISTS). Commit al exito. Retorna el numero de statements aplicados (split por ;), minimo 1 si el script no esta vacio."
+tags: [postgres, market-intel, infra]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [psycopg2]
+params:
+  - name: dsn
+    desc: "Cadena de conexion PostgreSQL en formato postgresql://user:pass@host:port/dbname."
+  - name: sql_path
+    desc: "Ruta al archivo .sql a aplicar (ej. db/migrations/001_init.sql)."
+output: "Numero entero de statements no vacios aplicados (split por ;), minimo 1 si el script no esta vacio; 0 si el archivo esta vacio."
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/infra/pg_apply_sql.py"
+---
+
+## Ejemplo
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "python", "functions"))
+from infra.pg_apply_sql import pg_apply_sql
+
+dsn = "postgresql://scraper:secret@localhost:5432/captacion"
+# db/migrations/001_init.sql con:
+#   CREATE TABLE IF NOT EXISTS leads_raw (
+#       id SERIAL PRIMARY KEY, name TEXT, city TEXT, score INT,
+#       snapshot_date DATE
+#   );
+n = pg_apply_sql(dsn, "db/migrations/001_init.sql")
+print(f"aplicados {n} statements")  # aplicados 1 statements
+```
+
+## Cuando usarla
+
+Cuando necesitas aplicar un archivo de migracion `.sql` (crear tablas, indices, columnas)
+a Postgres antes de escribir datos. Usala al arrancar el pipeline de captacion_clientes
+para garantizar el schema, y para iterar sobre `db/migrations/*.sql` en orden.
+
+## Gotchas
+
+- Idempotencia depende del SQL: el archivo DEBE usar `IF NOT EXISTS` / `ON CONFLICT` para poder re-aplicarse sin error. Esta funcion no lleva control de versiones de migracion — el caller decide que archivos aplica y en que orden.
+- Todo el script va en UNA transaccion: si cualquier statement falla, se hace rollback de todo el archivo y se lanza RuntimeError.
+- El conteo de statements (`split(";")`) es informativo y aproximado: un `;` dentro de un string literal o de un cuerpo de funcion PL/pgSQL infla la cuenta. No lo uses como verdad exacta, solo como indicador.
+- NO pasa parametros: el contenido del `.sql` se ejecuta tal cual. No metas datos no confiables en el archivo — es para DDL/migraciones controladas, no para input de usuario.
+- Requiere `psycopg2` instalado en el venv (import perezoso: el modulo importa sin la dependencia, pero la llamada falla con RuntimeError claro si falta).
+- Archivo inexistente o ilegible lanza RuntimeError con la ruta.