logsayer 0.6.0__py3-none-any.whl

logsayer/__init__.py

@@ -0,0 +1,3 @@
+"""logsayer — CLI del sistema de 5 capas documentales para proyectos con agentes IA."""
+
+__version__ = "0.6.0"

logsayer/__main__.py

@@ -0,0 +1,4 @@
+from logsayer.cli import app
+
+if __name__ == "__main__":
+    app()

logsayer/adapters/__init__.py

@@ -0,0 +1,10 @@
+"""Adaptadores por agente: wrappers finos que llaman al motor único (spec §6).
+
+Cada adaptador solo traduce la convención de archivos nativa de una
+herramienta (opencode, Claude Code, ...) e invoca comandos del CLI.
+"""
+
+from logsayer.adapters.base import AdapterFile, AdapterSpec
+from logsayer.adapters.registry import REGISTRY
+
+__all__ = ["AdapterFile", "AdapterSpec", "REGISTRY"]

logsayer/adapters/base.py

@@ -0,0 +1,21 @@
+"""Contrato declarativo de los adaptadores por agente (spec §6)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AdapterFile:
+    """Archivo a generar para un adaptador: path relativo + template a renderizar."""
+
+    rel_path: str
+    template_name: str
+
+
+@dataclass(frozen=True)
+class AdapterSpec:
+    """Definición completa de lo que genera un adaptador de agente."""
+
+    name: str
+    files: tuple[AdapterFile, ...]

logsayer/adapters/claude.py

@@ -0,0 +1,22 @@
+"""Adaptador para Claude Code: subagentes por rol en `.claude/agents/` (spec §6).
+
+Cada archivo es un subagente en formato markdown de Claude (frontmatter
+`name`/`description`/`tools` + system prompt) que invoca comandos del CLI.
+"""
+
+from __future__ import annotations
+
+from logsayer.adapters.base import AdapterFile, AdapterSpec
+
+ROLES: tuple[str, ...] = ("mentat", "navigator", "reverend-mother", "truthsayer")
+
+claude_spec = AdapterSpec(
+    name="claude",
+    files=tuple(
+        AdapterFile(
+            f".claude/agents/{rol}.md",
+            f"adapters/claude/{rol}.md.j2",
+        )
+        for rol in ROLES
+    ),
+)

logsayer/adapters/generate.py

@@ -0,0 +1,39 @@
+"""Generación de archivos de adaptador en la raíz del proyecto usuaria."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from logsayer.adapters.base import AdapterSpec
+from logsayer.config import LogsayerConfig
+from logsayer.core.paths import require_logsayer_root
+
+
+def generate_adapters(base: Path, spec: AdapterSpec) -> tuple[Path, list[Path]]:
+    """Escribe los subagentes del adaptador en la raíz logsayer de `base`.
+
+    Devuelve (raíz del proyecto, paths generados). Requiere raíz logsayer:
+    la estructura generada vive dentro de un proyecto ya scaffolded.
+    """
+    root = require_logsayer_root(base)
+    config = LogsayerConfig.load(root / "logsayer.toml")
+    env = Environment(
+        loader=PackageLoader("logsayer", "templates"),
+        autoescape=select_autoescape(("html", "xml")),
+    )
+    context = {
+        "project_name": root.name,
+        "audit_threshold_hus": config.audit_threshold_hus,
+        "bitacora_max_lines": config.bitacora_max_lines,
+        "context_threshold_percent": config.context_threshold_percent,
+    }
+    written: list[Path] = []
+    for adapter_file in spec.files:
+        rendered = env.get_template(adapter_file.template_name).render(**context)
+        target = root / adapter_file.rel_path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(rendered, encoding="utf-8")
+        written.append(target)
+    return root, written

logsayer/adapters/opencode.py

@@ -0,0 +1,22 @@
+"""Adaptador para opencode: subagentes por rol en `.opencode/agents/` (spec §6).
+
+Cada archivo es un agente en formato markdown de opencode (frontmatter
+`description`/`mode`/`permissions` + system prompt) que invoca comandos del CLI.
+"""
+
+from __future__ import annotations
+
+from logsayer.adapters.base import AdapterFile, AdapterSpec
+
+ROLES: tuple[str, ...] = ("mentat", "navigator", "reverend-mother", "truthsayer")
+
+opencode_spec = AdapterSpec(
+    name="opencode",
+    files=tuple(
+        AdapterFile(
+            f".opencode/agents/{rol}.md",
+            f"adapters/opencode/{rol}.md.j2",
+        )
+        for rol in ROLES
+    ),
+)

logsayer/adapters/registry.py

@@ -0,0 +1,38 @@
+"""Registro de adaptadores disponibles y resolución por nombre (spec §5)."""
+
+from __future__ import annotations
+
+from logsayer.adapters.base import AdapterSpec
+from logsayer.adapters.claude import claude_spec
+from logsayer.adapters.opencode import opencode_spec
+
+REGISTRY: dict[str, AdapterSpec] = {
+    "opencode": opencode_spec,
+    "claude": claude_spec,
+}
+
+# Conocidos por el spec §5 pero aún sin adaptador (fase 3: solo opencode y claude).
+NOT_YET_IMPLEMENTED: frozenset[str] = frozenset(
+    {"copilot", "cursor", "gemini", "hermes"}
+)
+
+SUPPORTED: frozenset[str] = frozenset(REGISTRY)
+
+
+class AgentError(Exception):
+    """Error controlado al resolver o generar un adaptador."""
+
+
+def resolve_adapter(agent: str) -> AdapterSpec:
+    if agent in REGISTRY:
+        return REGISTRY[agent]
+    if agent in NOT_YET_IMPLEMENTED:
+        raise AgentError(
+            f"Adaptador {agent!r} aún no implementado. "
+            "Fase 3 soporta: " + ", ".join(sorted(SUPPORTED)) + "."
+        )
+    raise AgentError(
+        f"Agente desconocido {agent!r}. Soporta: "
+        + ", ".join(sorted(SUPPORTED))
+        + "."
+    )

logsayer/cli.py

@@ -0,0 +1,311 @@
+"""Interfaz de línea de comandos de logsayer (Typer)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from logsayer.adapters.generate import generate_adapters
+from logsayer.adapters.registry import AgentError, resolve_adapter
+from logsayer.config import LogsayerConfig
+from logsayer.core import audit, fremen, logbook, project, specs, suk
+from logsayer.core.checks import CheckResult
+from logsayer.core.paths import ProjectRootError, require_logsayer_root
+from logsayer.core.project import project_name
+from logsayer.scaffold import (
+    RENDERED_FILES,
+    ScaffoldError,
+    resolve_target,
+    scaffold,
+)
+
+app = typer.Typer(
+    help="logsayer — sistema de 5 capas documentales para proyectos con agentes IA.",
+    no_args_is_help=True,
+)
+
+_ROLES: tuple[tuple[str, str], ...] = (
+    ("mentat", "Capa 1 — Especificacion (Mentat)."),
+    ("navigator", "Capa 2 — Estado (Navegante)."),
+    ("reverend-mother", "Capa 3 — Bitacora (Reverenda Madre)."),
+    ("truthsayer", "Capa 4 — Verificacion semantica (Decidora)."),
+    ("suk", "Capa 4 — Verificacion mecanica (Suk Doctor)."),
+    ("fremen", "Capa 5 — Proceso (Fremen)."),
+)
+
+_role_typers: dict[str, typer.Typer] = {}
+for _name, _help in _ROLES:
+    _role_typers[_name] = typer.Typer(help=_help, no_args_is_help=True)
+    app.add_typer(_role_typers[_name], name=_name)
+
+
+def _register_with_alias(role: str, sub: typer.Typer, name: str) -> None:
+    """Registra `sub` bajo el grupo del rol y con alias plano en la raíz (spec §5)."""
+    _role_typers[role].add_typer(sub, name=name)
+    app.add_typer(sub, name=name)
+
+
+@app.command()
+def init(
+    project_name: Annotated[
+        str | None,
+        typer.Argument(help="Nombre del proyecto a scaffoldear."),
+    ] = None,
+    here: Annotated[
+        bool,
+        typer.Option("--here", help="Scaffoldea en el directorio actual."),
+    ] = False,
+) -> None:
+    """Inicializa la estructura docs/ + AGENTS.md + logsayer.toml."""
+    try:
+        target, name = resolve_target(project_name, here, Path.cwd())
+        existing = {rel for rel in RENDERED_FILES if (target / rel).is_file()}
+        written = scaffold(target, name, LogsayerConfig.load(), adopt=here)
+    except ScaffoldError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    typer.echo(f"Scaffold listo en {target}")
+    if here and existing:
+        typer.echo("Modo adopt: preservados (ya existían, no se sobrescriben):")
+        for rel in sorted(existing):
+            typer.echo(f"  - {rel}")
+    for written_path in written:
+        typer.echo(f"Generado: {written_path}")
+
+
+agent_typer = typer.Typer(
+    help="Adaptadores por agente (Capa: coordinación multi-agente).",
+    no_args_is_help=True,
+)
+
+
+@agent_typer.command("add")
+def agent_add(
+    agent: Annotated[
+        str,
+        typer.Argument(help="Agente destino (opencode | claude)."),
+    ],
+) -> None:
+    """Genera subagentes por rol en la convención nativa del agente."""
+    try:
+        spec = resolve_adapter(agent)
+        root, written = generate_adapters(Path.cwd(), spec)
+    except (AgentError, ProjectRootError) as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    for path in written:
+        typer.echo(f"Generado: {path.relative_to(root)}")
+
+
+app.add_typer(agent_typer, name="agent")
+
+
+spec_typer = typer.Typer(
+    help="Historias de usuario (Capa 1).",
+    no_args_is_help=True,
+)
+
+
+@spec_typer.command("new")
+def spec_new(
+    hu: Annotated[str, typer.Argument(help="Identificador de la HU (ej: HU-01).")],
+) -> None:
+    """Crea una HU con template mínimo en 04_user_stories/."""
+    try:
+        root = require_logsayer_root(Path.cwd())
+        target = specs.create_hu(root, hu)
+    except (ProjectRootError, specs.SpecError) as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    typer.echo(f"HU {hu} creada en {target}")
+
+
+_register_with_alias("mentat", spec_typer, "spec")
+
+
+state_typer = typer.Typer(
+    help="Snapshot del estado del proyecto (Capa 2).",
+    no_args_is_help=True,
+)
+
+
+@state_typer.command("show")
+def state_show() -> None:
+    """Imprime docs/project_state.md (lectura obligatoria al iniciar sesión)."""
+    try:
+        root = require_logsayer_root(Path.cwd())
+        state = project.state_file(root)
+    except ProjectRootError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    if not state.is_file():
+        raise typer.BadParameter(f"No existe {state}. Se crea con 'logsayer init'.")
+    typer.echo(state.read_text(encoding="utf-8").rstrip())
+
+
+_register_with_alias("navigator", state_typer, "state")
+
+
+log_typer = typer.Typer(
+    help="Bitácora append-only, particionada (Capa 3).",
+    no_args_is_help=True,
+)
+
+
+@log_typer.command("add")
+def log_add(
+    text: Annotated[str, typer.Argument(help="Texto de la entrada de bitácora.")],
+    phase: Annotated[
+        str | None,
+        typer.Option(
+            "--fase",
+            help="Fase del logbook (default: fase actual de project_state.md).",
+        ),
+    ] = None,
+) -> None:
+    """Agrega una entrada al logbook activo; particiona si supera el límite."""
+    try:
+        root = require_logsayer_root(Path.cwd())
+        config = LogsayerConfig.load(root / "logsayer.toml")
+        result = logbook.add_entry(root, text, config, phase_override=phase)
+    except (ProjectRootError, logbook.LogbookError) as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    path = result["path"]
+    assert isinstance(path, Path)
+    typer.echo(f"Entrada registrada en {path.relative_to(root)}")
+
+
+@log_typer.command("index")
+def log_index() -> None:
+    """Reconstruye docs/logbooks/00_index.md desde los archivos reales."""
+    try:
+        root = require_logsayer_root(Path.cwd())
+        index_path = logbook.write_index(root)
+    except (ProjectRootError, logbook.LogbookError) as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    typer.echo(f"Índice actualizado en {index_path.relative_to(root)}")
+
+
+_register_with_alias("reverend-mother", log_typer, "log")
+
+
+audit_typer = typer.Typer(
+    help="Verificación semántica spec-vs-código (Capa 4).",
+    no_args_is_help=True,
+)
+
+
+@audit_typer.command("run")
+def audit_run(
+    reset_counter: Annotated[
+        bool,
+        typer.Option(
+            "--reset-counter",
+            help="Reinicia el contador de HUs en project_state.md tras la corrida.",
+        ),
+    ] = False,
+) -> None:
+    """Genera la estructura del reporte y el prompt; el resultado
+    lo produce la Decidora."""
+    try:
+        root = require_logsayer_root(Path.cwd())
+        report = audit.run_audit(root)
+        if reset_counter:
+            project.set_closed_hus(root, 0)
+    except (ProjectRootError, audit.AuditError, ValueError) as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    typer.echo(f"Estructura y prompt generados en {report.relative_to(root)}")
+    if reset_counter:
+        typer.echo("Contador de HUs reiniciado a 0 en project_state.md.")
+    else:
+        typer.echo("Contador intacto. Al aprobar, corre de nuevo con --reset-counter.")
+
+
+@audit_typer.command("status")
+def audit_status() -> None:
+    """Muestra el contador de HUs vs el umbral y el último reporte."""
+    try:
+        root = require_logsayer_root(Path.cwd())
+        config = LogsayerConfig.load(root / "logsayer.toml")
+        closed = project.read_closed_hus(root)
+        last = audit.last_audit(root)
+        threshold = config.audit_threshold_hus
+    except ProjectRootError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    current = f"HUs cerradas desde la última auditoría: {closed}"
+    typer.echo(f"{current} (umbral: {threshold})")
+    if last is None:
+        typer.echo("Última auditoría: ninguna reportada.")
+    else:
+        typer.echo(f"Última auditoría: {last.name} ({last.relative_to(root)})")
+    if closed >= threshold:
+        typer.echo("Estado: corresponde auditar. Ejecuta: logsayer audit run")
+    else:
+        missing = threshold - closed
+        typer.echo(f"Estado: no corresponde auditar (faltan {missing} HUs).")
+
+
+_register_with_alias("truthsayer", audit_typer, "audit")
+
+
+def _render_checks(title: str, results: list[CheckResult]) -> None:
+    """Imprime el reporte de chequeos y sale con código 1 si algo falló."""
+    typer.echo(f"{title}\n")
+    failed = 0
+    for result in results:
+        mark = "✔" if result.ok else "✘"
+        typer.echo(f"{mark} {result.name}: {result.detail or 'OK'}")
+        if not result.ok:
+            failed += 1
+    typer.echo()
+    if failed:
+        message = (
+            f"Estado: {failed} chequeo(s) fallido(s). "
+            "Corrige antes de continuar."
+        )
+        typer.echo(message)
+        raise typer.Exit(code=1)
+    typer.echo("Estado: sano.")
+
+
+@_role_typers["suk"].command("doctor")
+def suk_doctor() -> None:
+    """Chequeo mecánico: estructura y no mezcla de capas (Suk Doctor)."""
+    try:
+        root = require_logsayer_root(Path.cwd())
+        results = suk.run_suk(root)
+    except ProjectRootError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    title = f"Suk Doctor — verificación mecánica de {project_name(root)}"
+    _render_checks(title, results)
+
+
+@app.command("check")
+def check() -> None:
+    """Alias plano de `suk doctor` (spec §5)."""
+    suk_doctor()
+
+
+@_role_typers["fremen"].command("verify")
+def fremen_verify() -> None:
+    """Chequeo de proceso: marco operativo y Definition of Ready (Fremen)."""
+    try:
+        root = require_logsayer_root(Path.cwd())
+        results = fremen.run_fremen(root)
+    except ProjectRootError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    title = f"Fremen — verificación de proceso de {project_name(root)}"
+    _render_checks(title, results)
+
+
+process_typer = typer.Typer(
+    help="Chequeo de proceso (Capa 5 — Fremen).",
+    no_args_is_help=True,
+)
+
+
+@process_typer.command("check")
+def process_check() -> None:
+    """Alias plano de `fremen verify` (spec §5)."""
+    fremen_verify()
+
+
+app.add_typer(process_typer, name="process")

logsayer/config.py

@@ -0,0 +1,62 @@
+"""Carga y validación de la configuración `logsayer.toml` (tabla `[logsayer]`)."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _number(value: object, field: str) -> float:
+    if not isinstance(value, (int, float)):
+        raise ValueError(f"{field} debe ser un numero.")
+    return float(value)
+
+
+def _integer(value: object, field: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"{field} debe ser un entero.")
+    return value
+
+
+@dataclass(frozen=True)
+class LogsayerConfig:
+    """Umbrales de configuración del framework (sección 4 de la spec maestra)."""
+
+    session_close_context_threshold: float = 0.70
+    bitacora_max_lines: int = 400
+    audit_threshold_hus: int = 3
+
+    @property
+    def context_threshold_percent(self) -> int:
+        return round(self.session_close_context_threshold * 100)
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> LogsayerConfig:
+        """Carga `logsayer.toml`; si no existe o le falta `[logsayer]`, usa defaults."""
+        if path is None or not path.is_file():
+            return cls()
+        with path.open("rb") as fh:
+            data = tomllib.load(fh)
+        section = data.get("logsayer")
+        if section is None:
+            return cls()
+        if not isinstance(section, dict):
+            raise ValueError("La tabla [logsayer] debe ser un TOML table.")
+
+        threshold = _number(
+            section.get("session_close_context_threshold", 0.70),
+            "session_close_context_threshold",
+        )
+        if not 0.0 < threshold < 1.0:
+            raise ValueError("session_close_context_threshold debe estar entre 0 y 1.")
+        max_lines = _integer(
+            section.get("bitacora_max_lines", 400),
+            "bitacora_max_lines",
+        )
+        hus = _integer(section.get("audit_threshold_hus", 3), "audit_threshold_hus")
+        return cls(
+            session_close_context_threshold=threshold,
+            bitacora_max_lines=max_lines,
+            audit_threshold_hus=hus,
+        )

logsayer/core/__init__.py

@@ -0,0 +1 @@
+"""Motor único de logsayer: lógica de dominio independiente del agente (spec §6)."""

logsayer/core/audit.py

@@ -0,0 +1,81 @@
+"""Auditoría spec-vs-código (Capa 4 — Decidora de Verdad).
+
+El CLI genera la estructura del reporte y el prompt; el resultado lo produce el
+subagente que ejecuta la auditoría (spec §10: no prometer resultado determinístico).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from logsayer.core.project import project_name, read_closed_hus
+
+AUDITS_DIR = Path("docs") / "06_audits"
+
+
+class AuditError(Exception):
+    """Error controlado de auditoría."""
+
+
+def _render(template: str, **context: object) -> str:
+    env = Environment(
+        loader=PackageLoader("logsayer", "templates"),
+        autoescape=select_autoescape(("html", "xml")),
+    )
+    return env.get_template(template).render(**context)
+
+
+def _next_report_path(root: Path, date: str) -> Path:
+    audits_dir = root / AUDITS_DIR
+    audits_dir.mkdir(parents=True, exist_ok=True)
+    counter = 0
+    while True:
+        suffix = "" if counter == 0 else f"-{counter}"
+        candidate = audits_dir / f"audit_{date}{suffix}.md"
+        if not candidate.exists():
+            return candidate
+        counter += 1
+
+
+def last_audit(root: Path) -> Path | None:
+    audits_dir = root / AUDITS_DIR
+    if not audits_dir.is_dir():
+        return None
+    reports = [
+        path
+        for path in audits_dir.glob("audit_*.md")
+        if not path.name.endswith(".prompt.md")
+    ]
+    if not reports:
+        return None
+    return max(reports)
+
+
+def run_audit(root: Path) -> Path:
+    """Genera el reporte y el prompt de auditoría para la Decidora."""
+    date = datetime.now().strftime("%Y-%m-%d")
+    report = _next_report_path(root, date)
+    name = project_name(root)
+    closed = read_closed_hus(root)
+    report.write_text(
+        _render(
+            "audit_report.md.j2",
+            date=date,
+            project_name=name,
+            closed_hus=closed,
+        )
+    )
+    prompt = report.with_suffix(".prompt.md")
+    prompt.write_text(
+        _render(
+            "audit_prompt.md.j2",
+            date=date,
+            project_name=name,
+            closed_hus=closed,
+            report_name=report.name,
+        )
+    )
+    return report

logsayer/core/checks.py

@@ -0,0 +1,22 @@
+"""Resultado de chequeos determinísticos (bots: Suk Doctor y Fremen)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """Resultado de un chequeo único con criterio objetivo (sin juicio)."""
+
+    name: str
+    ok: bool
+    detail: str
+
+
+def ok(name: str, detail: str = "OK") -> CheckResult:
+    return CheckResult(name=name, ok=True, detail=detail)
+
+
+def fail(name: str, detail: str) -> CheckResult:
+    return CheckResult(name=name, ok=False, detail=detail)