llm-dev-core 0.3.0__tar.gz → 0.4.0__tar.gz

{llm_dev_core-0.3.0 → llm_dev_core-0.4.0}/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # ARCHITECTURE.md — llm-dev-core
 
-> **Estado:** v0.3 (seed revisado) · **Última revisión:** 2026-09-21
+> **Estado:** v0.4 (seed revisado) · **Última revisión:** 2026-09-22
 > **Audiencia:** yo en 52 semanas, cualquiera que revise este repo, y entrevistadores técnicos.
 
 ---
@@ -131,7 +131,7 @@ La reparación tiene **presupuesto**: máximo 2 intentos y un cap de costo por m
 
 ```yaml
 id: commit-message-generator
-version: 0.3.0
+version: 0.4.0
 owner: llm-dev-core
 model_family: gpt-4o-mini
 schema: CommitMessage
@@ -339,11 +339,11 @@ La regla es simple: si no puedes pagar el eval de forma repetible, el eval está
 
 ## 10. Estado actual
 
-- **Versión:** v0.3
-- **Módulos existentes:** `packages/llm-client` v0.1.0 (seed sem. 2) — `complete`/`stream`, retry+backoff+jitter, reparación con tope, cap de costo, cache, span de 20 campos, record/replay nativo, transportes `opencode` (sesión local sin API key) y `openai-compatible` (HTTP). `packages/schema-validate` v0.1.0 (seed sem. 3) — validación Pydantic de la salida LLM (ADR-2): JSON con/sin caretas, errores campo a campo, registro `SchemaId → modelo`, `parsed` en `ValidationResult`; compone con `llm-client` vía el hook `validator`.
-- **Consumidores:** `Proyectos/commit-cli` (sem. 2) — CLI que propone mensajes de commit desde `git diff`; `Proyectos/release-scribe` (sem. 3) — release notes JSON validadas por `schema-validate` desde `git log`. Ambos dependen de la dist unificada `llm-dev-core` (editable). La métrica de reutilización real se medirá en §10.1 desde el corte de semanal.
-- **Empaquetado:** una sola dist `llm-dev-core`, publicable vía `uv build`/`uv publish` con `llm_client` y `schema_validate` top-level (D1). Pendiente la primera publicación real en PyPI (se cierra en la sem. 3 con v0.3).
-- **Enforcement:** ADR-0, ADR-1 (`llm-client-contract`) y ADR-2 (`schema-validate-contract`) en `docs/decisions/`, plantillas en `templates/`, `make validate` (estructura + tests) y `make validate-consumer CONSUMER=../<repo>`.
+- **Versión:** v0.4
+- **Módulos existentes:** `packages/llm-client` v0.1.0 (seed sem. 2) — `complete`/`stream`, retry+backoff+jitter, reparación con tope, cap de costo, cache, span de 20 campos, record/replay nativo, transportes `opencode` (sesión local sin API key) y `openai-compatible` (HTTP). `packages/schema-validate` v0.1.0 (seed sem. 3) — validación Pydantic de la salida LLM (ADR-2): JSON con/sin caretas, errores campo a campo, registro `SchemaId → modelo`, `parsed` en `ValidationResult`; compone con `llm-client` vía el hook `validator`. `packages/secure-base` v0.1.0 (seed sem. 4) — utilidad de máscara (ADR-3): `detect`/`redact`/`sanitize_for_prompt`/`assert_redacted` + `SecurityProfile`; máscara unidireccional y determinista (placeholder `[REDACTED:<tipo>:<n>]`), 9 detectores, hoja de la seguridad (no depende de `llm-client` ni `schema-validate`); compone en los renderers, antes de que el texto cruce al proveedor.
+- **Consumidores:** `Proyectos/commit-cli` (sem. 2) — CLI que propone mensajes de commit desde `git diff`; `Proyectos/release-scribe` (sem. 3) — release notes JSON validadas por `schema-validate` desde `git log`; `Proyectos/sec-check` (sem. 4) — escáner de secretos con triaje LLM: redacta con `secure-base` y aborta si `assert_redacted` no es vacío, reporte `sec-findings-v1` validado por `schema-validate`. Los tres dependen de la dist unificada `llm-dev-core` (editable). La métrica de reutilización real se medirá en §10.1 desde el corte de semanal.
+- **Empaquetado:** una sola dist `llm-dev-core` (D1) publicada en PyPI: `llm_client`, `schema_validate` y `secure_base` top-level. La publicación es automática desde tag `v*` vía trusted publishing OIDC (workflow `publish.yml`, sin tokens guardados).
+- **Enforcement:** ADR-0, ADR-1 (`llm-client-contract`), ADR-2 (`schema-validate-contract`) y ADR-3 (`secure-base-contract`) en `docs/decisions/`, plantillas en `templates/`, `make validate` (estructura + tests) y `make validate-consumer CONSUMER=../<repo>`.
 - **Pasos por semana según el plan:** se mantiene el calendario semanal (estructura C1–C18 de §5, armonizada en la sem. 3): `schema-validate` (sem. 3), `secure-base` (sem. 4), `test-kit` (sem. 5), `web-api-base` (sem. 6), `ci-pack` (sem. 7), `cache-ratelimit` (sem. 8), `bot-base` (sem. 9), `parser-io` (sem. 10), `docs-gen` (sem. 12), ... hasta `cost-obs` (sem. 39).
 - **Próximo hito:** v1.0 en la semana 13, con 12 consumidores reales detrás.
 

{llm_dev_core-0.3.0 → llm_dev_core-0.4.0}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 La versión es la del paquete `llm-dev-core`. El historial comienza con **v1.0 (semana 13)** — hasta entonces el core es `0.x` y puede romperse sin aviso (D3).
 
+## v0.4 — 2026-09-22 (secure-base seed)
+
+- Semana 4: nace `packages/secure-base` v0.1.0 dentro de un consumidor real (`sec-check`).
+  - Contrato ADR-3: `detect`/`redact`/`sanitize_for_prompt`/`assert_redacted` + `SecurityProfile` (declaración
+    de tipos para el lint anti-secretos de `ci-pack`, sem. 7).
+  - Máscara unidireccional y determinista: placeholder `[REDACTED:<tipo>:<n>]`; `Finding.match` es preview
+    truncado (24 chars), nunca el secreto completo. 9 detectores (email, phone, ipv4, credit_card, aws_access_key,
+    github_token, private_key, bearer, url_userinfo).
+  - `secure-base` es hoja (no depende de `llm-client` ni de `schema-validate`); se compone en el renderer del
+    consumidor, antes de que el texto cruce al proveedor.
+- Tercer consumidor: `Proyectos/sec-check` (sem. 4) — escáner de secretos con triaje LLM: detecta en `git diff`
+  o archivo, redacta con `secure-base`, aborta si `assert_redacted` no es vacío, y solo el texto enmascarado viaja
+  al LLM (`opencode` local o replay). Reporte `sec-findings-v1` validado con `schema-validate`; exit 0 sin secretos,
+  1 con secretos, 2 inválido. Tape real grabado con 3 hallazgos críticos, replay en verde.
+- Wheel unificado (D1): `llm-dev-core 0.4.0` ahora empaqueta `llm_client` + `schema_validate` + `secure_base`
+  top-level. `make validate` y `validate-consumer` (3 consumidores) en verde; 37 tests.
+- Publicado `llm-dev-core 0.4.0` en PyPI (trusted publishing, tag `v0.4.0`).
+
 ## v0.3 — 2026-09-21 (schema-validate seed + dist unificada)
 
 - Semana 3: nace `packages/schema-validate` v0.1.0 dentro de un consumidor real (`release-scribe`).
@@ -19,6 +37,8 @@ La versión es la del paquete `llm-dev-core`. El historial comienza con **v1.0 (
   `web-api-base` (6), `ci-pack` (7), `cache-ratelimit` (8), `bot-base` (9), … hasta `cost-obs` (39).
   Deuda aprobada en el review: la sem-2 quería publicar ya en PyPI; al unificar el empaquetado, la primera
   publicación real pasa a ser esta v0.3.
+- Publicado `llm-dev-core 0.3.0` en PyPI (trusted publishing OIDC, workflow `publish.yml` en tags `v*`):
+  primera release real del core; instalable y verificado desde el registro (D1).
 
 ## v0.2 — 2026-09-20 (llm-client seed)
 

{llm_dev_core-0.3.0 → llm_dev_core-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: llm-dev-core
-Version: 0.3.0
+Version: 0.4.0
 Summary: Núcleo versionado del que dependen 52 proyectos en 52 semanas: un solo sistema acumulativo.
 Author-email: binahco <binahco.sas@gmail.com>
 Requires-Python: >=3.12

{llm_dev_core-0.3.0 → llm_dev_core-0.4.0}/README.md

@@ -6,15 +6,15 @@ Núcleo versionado y publicado del que dependen 52 proyectos en 52 semanas: un s
 
 Toda llamada a un LLM pasa por `llm-client`, toda salida no confiable pasa por `schema-validate`, todo prompt vive en `prompt-registry`. Ver `ARCHITECTURE.md` para la tesis, las decisiones (D1–D12) y las métricas verificables.
 
-- **Estado:** v0.3 · Semana 3
+- **Estado:** v0.4 · Semana 4
 - **Stack:** Python 3.12+ (ADR-0, `docs/decisions/0000-stack.md`)
 - **Estructura:** `packages/` (módulos), `templates/` (consumidor clonable), `scripts/` (verificación), `docs/`
-- **Empaquetado:** una sola dist `llm-dev-core` (D1): `llm_client` y `schema_validate` top-level; los consumidores dependen de `llm-dev-core ^0.x`, nunca de módulos sueltos.
+- **Empaquetado:** una sola dist `llm-dev-core` (D1): `llm_client`, `schema_validate` y `secure_base` top-level; los consumidores dependen de `llm-dev-core ^0.x`, nunca de módulos sueltos.
 
 ## Desarrollo
 
 ```bash
 uv sync        # instala el workspace
 make validate  # invariantes: estructura, plantillas, ADR-0, sintaxis
-uv run pytest  # tests (aún ninguno hasta sem. 2)
+uv run pytest  # tests (37 a la fecha)
 ```

llm_dev_core-0.4.0/docs/decisions/0003-secure-base-contract.md

@@ -0,0 +1,66 @@
+# Contrato mínimo — `secure-base`
+
+- **Fecha:** 2026-09-22
+- **Estado:** aceptada
+- **Origen:** §3.1 en `ARCHITECTURE.md`
+- **Implementada en:** semana 4 (`packages/secure-base` v0.1.0, nacida dentro de `sec-check`)
+
+Este documento es el contrato escrito contra el que se implementa la semana 4. Define la utilidad de
+máscara que exige §3.1.1 y el perfil de declaración que alimentará los lints de `ci-pack` (sem. 7).
+
+## 1. API conceptual
+
+```python
+detect(text) -> list[Finding]            # hallazgos tipados (sin mutar texto)
+redact(text) -> RedactResult             # texto enmascarado + hallazgos
+sanitize_for_prompt(text) -> RedactResult  # alias semántico para renderers
+assert_redacted(text, profile?) -> list[Finding]  # violaciones de §3.1
+```
+
+```python
+class Finding(BaseModel):
+    type: str        # email | phone | ipv4 | credit_card | aws_access_key | github_token | private_key | bearer | url_userinfo
+    match: str       # preview truncado (24 chars) — NUNCA el secreto completo
+    offset: int      # offset del primer carácter
+    length: int      # para reemplazos deterministas
+    line: int        # 1-based
+```
+
+## 2. Reglas de la máscara
+
+- **Unidireccional:** el secreto crudo no se conserva en ningún lugar del resultado. No hay operación inversa.
+- **Determinista:** misma entrada → misma salida (mismo texto y mismos placeholders).
+- **Placeholder:** `[REDACTED:<type>:<n>]`, con `n` por tipo (1-based, en orden de aparición).
+- **`Finding.match` es un preview truncado**: suficiente para triaje, insuficiente para re-inyectar el secreto.
+- **`detect` es no destructivo**: el scanner se usa antes de decidir qué se envía; `redact` produce la salida
+  que sí puede cruzar el límite del prompt.
+
+## 3. Perfil y lints (§3.1.1 → ci-pack)
+
+- `SecurityProfile(data_types: list[str])`: qué tipos declara manejar el consumidor.
+- `assert_redacted(text, profile) -> list[Finding]`: si el resultado **no está vacío**, el texto aún contiene
+  secretos en claro declarados por el perfil → violación de la regla 1 de §3.1.
+- El enforcement operativo (que el build falle si un prompt de producción llega con secretos) se implementa
+  en `ci-pack` (sem. 7); `secure-base` es el motor que ese lint usaría.
+
+## 4. Composición con el resto del core
+
+- `secure-base` **no depende de `llm-client`** ni de `schema-validate`: es la hoja de la seguridad. Se compone
+  en el renderer del consumidor (antes de construir los mensajes) y en el preámbulo del flujo.
+- `llm-client` redacta `<variable>` en sus spans por contrato (ADR-1, §1); `secure-base` hace lo mismo aguas
+  arriba, sobre el payload que podría entrar a un prompt.
+
+## 5. Qué NO contrata este documento
+
+- No define el lint anti-prompts (sem. 7, `ci-pack`): solo su motor de detección.
+- No reemplaza el manejo de secretos de la máquina del desarrollador: no es un gestor de claves.
+- No garantiza detección perfecta: los patrones son heurísticos; la prueba de que algo no se filtró es
+  estructural (el texto que sale de `redact` no contiene ningún hallazgo).
+
+## 6. Criterio de aceptación del contrato (semana 4)
+
+- [x] `detect` encuentra los 9 tipos en un texto de prueba y no delira con código limpio.
+- [x] `redact` es unidireccional y determinista: nada del secreto crudo sobrevive; mismo input → mismo output.
+- [x] `sanitize_for_prompt` deja `assert_redacted(...) == []` (el texto que cruza al proveedor está limpio).
+- [x] `assert_redacted(text, profile)` filtra por los tipos declarados.
+- [x] Primer consumidor real: `sec-check` (sem. 4), que redacta diffs antes de enviarlos al LLM.

{llm_dev_core-0.3.0 → llm_dev_core-0.4.0}/docs/metrics/README.md

@@ -2,6 +2,6 @@
 
 Datos crudos y agregados de la página de evidencia (§10.1).
 
-Estado actual: sin datos. Semanas 1–3 tienen consumidores (`commit-cli`, `release-scribe`) pero aún no hay
+Estado actual: sin datos. Semanas 1–4 tienen consumidores (`commit-cli`, `release-scribe`, `sec-check`) pero aún no hay
 llamadas agregadas ni corriendo en CI. El andamiaje (`scripts/collect_metrics.py`) se implementa en la
 semana 6 con `ci-pack`; a partir de ahí `docs/metrics/` se regenera en cada merge.

llm_dev_core-0.4.0/packages/secure-base/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "llm-dev-secure-base"
+version = "0.1.0"
+description = "secure-base: secretos y datos sensibles nunca entran en prompts sin redacción (§3.1)."
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.7",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/secure_base"]

llm_dev_core-0.4.0/packages/secure-base/src/secure_base/__init__.py

@@ -0,0 +1,14 @@
+from .findings import Finding
+from .profile import DATA_TYPE_NAMES, SecurityProfile, assert_redacted
+from .redact import RedactResult, detect, redact, sanitize_for_prompt
+
+__all__ = [
+    "DATA_TYPE_NAMES",
+    "Finding",
+    "RedactResult",
+    "SecurityProfile",
+    "assert_redacted",
+    "detect",
+    "redact",
+    "sanitize_for_prompt",
+]

llm_dev_core-0.4.0/packages/secure-base/src/secure_base/detectors.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .findings import Finding
+
+
+def _preview(raw: str, limit: int = 24) -> str:
+    match = raw[:limit]
+    return match + "…" if len(raw) > limit else match
+
+
+@dataclass(frozen=True)
+class Detector:
+    type: str
+    pattern: re.Pattern[str]
+
+    def scan(self, text: str) -> list[Finding]:
+        findings: list[Finding] = []
+        for m in self.pattern.finditer(text):
+            raw = m.group(0)
+            findings.append(
+                Finding(
+                    type=self.type,
+                    match=_preview(raw),
+                    offset=m.start(),
+                    length=len(raw),
+                    line=text.count("\n", 0, m.start()) + 1,
+                )
+            )
+        return findings
+
+
+DETECTORS: tuple[Detector, ...] = (
+    Detector("email", re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")),
+    Detector("phone", re.compile(r"(?:\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b")),
+    Detector("ipv4", re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")),
+    Detector("credit_card", re.compile(r"\b(?:\d{4}[ -]?){3}\d{4}\b")),
+    Detector("aws_access_key", re.compile(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b")),
+    Detector("github_token", re.compile(r"\b(?:ghp_|gho_|ghu_|ghs_|ghr_|github_pat_)[A-Za-z0-9_]{20,}\b")),
+    Detector("private_key", re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----")),
+    Detector("bearer", re.compile(r"\bBearer [A-Za-z0-9._~+/-]+=*\b")),
+    Detector("url_userinfo", re.compile(r"(?i)\b\w+://[\w.-]+:[^@\s]+@")),
+)
+
+
+def scan(text: str) -> list[Finding]:
+    findings: list[Finding] = []
+    for detector in DETECTORS:
+        findings.extend(detector.scan(text))
+    return sorted(findings, key=lambda f: (f.offset, f.type))

llm_dev_core-0.4.0/packages/secure-base/src/secure_base/findings.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel
+
+
+class Finding(BaseModel):
+    type: str
+    match: str
+    offset: int
+    length: int
+    line: int

llm_dev_core-0.4.0/packages/secure-base/src/secure_base/profile.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from .detectors import scan
+from .findings import Finding
+
+DATA_TYPE_NAMES = ("email", "phone", "ipv4", "credit_card", "aws_access_key", "github_token", "private_key", "bearer", "url_userinfo")
+
+
+class SecurityProfile(BaseModel):
+    """Qué tipos de datos declara manejar el consumidor (§3.1 y futuro lint de ci-pack)."""
+
+    data_types: list[str]
+
+
+def assert_redacted(text: str, profile: SecurityProfile | None = None) -> list[Finding]:
+    """Devuelve hallazgos que siguen en claro en `text`.
+
+    Si el texto se va a enviar a un proveedor externo, un resultado no vacío es una violación.
+    Con `profile`, filtra a los tipos declarados por el consumidor.
+    """
+    findings = scan(text)
+    if profile is None:
+        return findings
+    declared = set(profile.data_types)
+    return [f for f in findings if f.type in declared]

llm_dev_core-0.4.0/packages/secure-base/src/secure_base/redact.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from .detectors import scan
+from .findings import Finding
+
+
+class RedactResult(BaseModel):
+    text: str
+    findings: list[Finding]
+
+
+def detect(text: str) -> list[Finding]:
+    """Detecta secretos/PII sin redactar. Alimenta reportes y lints."""
+    return scan(text)
+
+
+def redact(text: str) -> RedactResult:
+    """Enmascara de forma unidireccional y determinista: el secreto crudo no queda en el texto."""
+    findings = scan(text)
+    counters: dict[str, int] = {}
+    pieces: list[str] = []
+    cursor = 0
+    for f in findings:
+        pieces.append(text[cursor : f.offset])
+        counters[f.type] = counters.get(f.type, 0) + 1
+        pieces.append(f"[REDACTED:{f.type}:{counters[f.type]}]")
+        cursor = f.offset + f.length
+    pieces.append(text[cursor:])
+    return RedactResult(text="".join(pieces), findings=findings)
+
+
+def sanitize_for_prompt(text: str) -> RedactResult:
+    """Alias semántico para el renderer: nada sensible entra al prompt."""
+    return redact(text)

llm_dev_core-0.4.0/packages/secure-base/tests/test_secure_base.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from secure_base import SecurityProfile, assert_redacted, detect, redact, sanitize_for_prompt
+
+SAMPLE = """prueba con persona@ejemplo.com y también conta@otra.co
+token ghp_AbCdEfGhIjKlMnOpQrStUvWxYz123456
+aws AKIAIOSFODNN7EXAMPLE en plena línea
+privada:
+-----BEGIN RSA PRIVATE KEY-----
+incluye https://usuario:pass@host.com/path
+Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.abc
+tel +57 300 123 4567 y tarjeta 4111 1111 1111 1111
+ip 192.168.0.1 cliente"""
+
+
+def test_detect_types_positive() -> None:
+    findings = detect(SAMPLE)
+    types = {f.type for f in findings}
+    assert {
+        "email",
+        "github_token",
+        "aws_access_key",
+        "private_key",
+        "url_userinfo",
+        "bearer",
+        "phone",
+        "credit_card",
+        "ipv4",
+    } == types
+
+
+def test_no_false_positive_on_plain_text() -> None:
+    findings = detect("solo código normal sin secretos: return None")
+    assert findings == []
+
+
+def test_redact_is_one_way_and_deterministic() -> None:
+    result = redact(SAMPLE)
+    assert "persona@ejemplo.com" not in result.text
+    assert "ghp_" not in result.text
+    assert "AKIA" not in result.text
+    assert "usuario:pass" not in result.text
+    assert "Bearer eyJ" not in result.text
+    second = redact(SAMPLE)
+    assert result.text == second.text
+
+
+def test_redact_keeps_placeholders_and_structure() -> None:
+    result = redact(SAMPLE)
+    assert "[REDACTED:email:1]" in result.text
+    assert "[REDACTED:private_key:1]" in result.text
+    assert result.findings
+    assert result.findings[0].line >= 1
+
+
+def test_sanitize_for_prompt_never_leaves_raw_secrets() -> None:
+    clean = sanitize_for_prompt(SAMPLE)
+    assert assert_redacted(clean.text) == []
+
+
+def test_assert_redacted_filters_by_profile() -> None:
+    profile = SecurityProfile(data_types=["email"])
+    findings = assert_redacted(SAMPLE, profile)
+    assert findings and all(f.type == "email" for f in findings)
+
+    ok = assert_redacted(redact(SAMPLE).text, profile)
+    assert ok == []
+
+
+def test_detect_reports_offset_and_line() -> None:
+    findings = detect(SAMPLE)
+    email = next(f for f in findings if f.type == "email")
+    assert email.offset == SAMPLE.find("persona@ejemplo.com")
+    assert SAMPLE.count("\n", 0, email.offset) + 1 == 1

{llm_dev_core-0.3.0 → llm_dev_core-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "llm-dev-core"
-version = "0.3.0"
+version = "0.4.0"
 description = "Núcleo versionado del que dependen 52 proyectos en 52 semanas: un solo sistema acumulativo."
 authors = [{ name = "binahco", email = "binahco.sas@gmail.com" }]
 requires-python = ">=3.12"
@@ -18,6 +18,7 @@ build-backend = "hatchling.build"
 packages = [
     "packages/llm-client/src/llm_client",
     "packages/schema-validate/src/schema_validate",
+    "packages/secure-base/src/secure_base",
 ]
 
 [tool.uv.workspace]