loadcoach 1.0.0__py3-none-any.whl

loadcoach/__about__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

loadcoach/__main__.py

@@ -0,0 +1,12 @@
+"""loadcoach.__main__ — ``python -m loadcoach``.
+
+Delegates to the Typer app, whose root callback starts ``serve`` when invoked with no subcommand
+(CLI Standards §1).
+"""
+
+from __future__ import annotations
+
+from loadcoach.cli.main import app
+
+if __name__ == "__main__":
+    app()

loadcoach/bootstrap.py

@@ -0,0 +1,157 @@
+"""loadcoach.bootstrap — the composition root: settings, logging and the ASGI app, wired once.
+
+This module sits outside the ``web``/``cli``/``services``/``domain`` layer ordering that
+``.importlinter`` enforces, precisely so it can import both configuration and the web layer.
+``loadcoach.cli`` never imports it directly — the ``web-cli-independence`` contract forbids any
+import chain from ``cli`` into ``web``, and this module imports ``web``. Instead, the CLI's
+``serve`` command hands uvicorn the dotted string
+``"loadcoach.bootstrap:create_app_from_environment"`` and lets uvicorn perform that import itself;
+a string literal is invisible to import-linter's static analysis, so the two surfaces stay decoupled
+at the source level while still running the same application in one process.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from fastapi import FastAPI
+from sqlalchemy import func, select
+
+from loadcoach.config import LOOPBACK_HOSTS, InsecureBindingError, LoadedSettings, load_settings
+from loadcoach.infrastructure.db.models import ApiToken
+from loadcoach.infrastructure.providers.factory import build_provider
+from loadcoach.observability.logging import configure_logging
+from loadcoach.services.database import Database, ensure_ready
+from loadcoach.services.models import import_manual_capability_scores, try_discover_models
+from loadcoach.services.task_profiles import import_task_profiles, read_task_profiles_file
+from loadcoach.web.app import create_app
+
+__all__ = ["Application", "bootstrap", "create_app_from_environment"]
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class Application:
+    """A fully wired application: the settings it was built from and its ASGI app."""
+
+    loaded_settings: LoadedSettings
+    app: FastAPI
+
+
+def _has_active_token(database: Database) -> bool:
+    """Return whether at least one non-revoked, unexpired API token exists.
+
+    The third member of ADR-0026's non-loopback refusal set — bind acknowledgement and
+    ``server.allowed_hosts`` are checked in :func:`loadcoach.config.load_settings`, which reads no
+    database; this one needs the database, because LoadCoach stores tokens in the ``api_tokens``
+    table (created by ``loadcoach token create``) rather than in ``config.toml`` — a token an
+    operator can issue and revoke without editing a file.
+    """
+    now = datetime.now(UTC)
+    with database.read() as session:
+        count = session.execute(
+            select(func.count())
+            .select_from(ApiToken)
+            .where(
+                ApiToken.revoked_at.is_(None),
+                (ApiToken.expires_at.is_(None)) | (ApiToken.expires_at > now),
+            )
+        ).scalar_one()
+    return count > 0
+
+
+def bootstrap() -> Application:
+    """Load configuration, configure logging, ready the database, build the app.
+
+    Reads configuration through the standard precedence chain (defaults, file, environment) with
+    no CLI-argument layer of its own: a caller that needs CLI overrides applies them as environment
+    variables before calling this function, which is what ``loadcoach.cli.commands.system.serve``
+    does.
+
+    The startup revision check (database standards §5.1) and the non-loopback token requirement
+    (ADR-0026) both run here, in the composition root, and deliberately not inside
+    :func:`~loadcoach.web.app.create_app` — that function is documented as a pure function of
+    :class:`~loadcoach.config.Settings` precisely so tests can build an app without touching the
+    filesystem, and opening a database is neither pure nor free.
+
+    The shipped task profiles are validated and imported here too, before anything can route: a
+    malformed profile is a startup failure (dev-plan P2 acceptance criterion 3), not a
+    routing-time surprise. Model discovery is best-effort
+    (:func:`~loadcoach.services.models.try_discover_models`) — spec §5 promises LoadCoach starts
+    and serves with no provider, so an unreachable one at startup degrades health rather than
+    blocking the server.
+
+    Returns:
+        The wired :class:`Application`.
+
+    Raises:
+        ConfigurationError: Configuration is invalid, or an unsafe bind combination is configured.
+        InsecureBindingError: ``server.host`` is not loopback and no active API token exists.
+        MigrationRequired: The database is behind head and ``storage.auto_migrate`` is false.
+        SchemaAhead: The database was written by a newer application version.
+        DatabaseUnavailable: The configured database could not be reached at all.
+        TaskProfileInvalid: A shipped task profile fails validation.
+    """
+    loaded = load_settings()
+    configure_logging(
+        level=loaded.settings.logging.level, log_format=loaded.settings.logging.format
+    )
+    database_url = loaded.settings.storage.database_url
+    if database_url is None:  # pragma: no cover — StorageSettings always fills this in
+        message = "no database_url configured"
+        raise RuntimeError(message)
+    with Database.from_url(
+        database_url, statement_timeout_ms=loaded.settings.storage.statement_timeout_ms
+    ) as database:
+        ensure_ready(
+            database,
+            auto_migrate=loaded.settings.storage.auto_migrate,
+            backup_retention=loaded.settings.storage.backup_retention,
+        )
+        if loaded.settings.server.host not in LOOPBACK_HOSTS and not _has_active_token(database):
+            raise InsecureBindingError(
+                "server.host is not loopback but no active API token exists. A non-loopback bind "
+                "must have at least one token created first: `loadcoach token create`.",
+                details={"field": "server.host", "host": loaded.settings.server.host},
+            )
+        if (
+            loaded.settings.server.host not in LOOPBACK_HOSTS
+            and not loaded.settings.server.trusted_proxies
+        ):
+            # ADR-0014 §7's startup warning (F5/M5C-5): LoadCoach speaks HTTP and expects a TLS
+            # reverse proxy on any non-loopback bind; `trusted_proxies` being set is the one
+            # piece of configuration that evidences one. Without it, warn — and say what breaks:
+            # the UI's cookies are `Secure`, so over plain HTTP beyond loopback the browser
+            # stores neither the CSRF nor the token cookie and the 401 page's flow cannot work.
+            logger.warning(
+                "server.plain_http_exposure",
+                extra={
+                    "host": loaded.settings.server.host,
+                    "detail": (
+                        "non-loopback bind with no [server] trusted_proxies configured: "
+                        "ADR-0014 §7 expects a TLS reverse proxy here. Over plain HTTP the "
+                        "browser refuses the UI's Secure cookies, so the tokened-bind page "
+                        "flow needs HTTPS or loopback; the bearer-token API is unaffected."
+                    ),
+                },
+            )
+        profiles = read_task_profiles_file()
+        import_task_profiles(database, profiles, now=datetime.now(UTC))
+        provider = build_provider(loaded.settings.provider)
+        try_discover_models(database, provider, now=datetime.now(UTC))
+        # After discovery: a manual score names a model by canonical_id and is skipped, not an
+        # error, if that model has not been discovered yet.
+        import_manual_capability_scores(database, now=datetime.now(UTC))
+    return Application(loaded_settings=loaded, app=create_app(loaded.settings))
+
+
+def create_app_from_environment() -> FastAPI:
+    """Zero-argument ASGI factory: the target uvicorn imports by dotted name.
+
+    See the module docstring for why this is referenced by string rather than imported directly by
+    ``loadcoach.cli``.
+    """
+    return bootstrap().app

loadcoach/cli/commands/config.py

@@ -0,0 +1,169 @@
+"""loadcoach.cli.commands.config — show, validate, init, path.
+
+Only ``typer`` and ``json`` load at module level; ``loadcoach.config`` (which imports pydantic) is
+imported lazily inside each command body, per the same startup-performance discipline as
+:mod:`loadcoach.cli.commands.system`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+__all__ = ["app"]
+
+app = typer.Typer(help="Configuration inspection and management.")
+
+
+def _looks_secret(field_name: str) -> bool:
+    lowered = field_name.lower()
+    return any(marker in lowered for marker in ("token", "key", "secret", "password"))
+
+
+@app.command("show")
+def show(
+    config: Annotated[
+        str | None, typer.Option("--config", help="Path to a config.toml file.")
+    ] = None,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Print JSON instead of a table.")
+    ] = False,
+) -> None:
+    """Print the effective configuration, with the source of every value.
+
+    Example:
+        loadcoach config show --json
+    """
+    from loadcoach.config import ConfigurationError, load_settings
+
+    try:
+        loaded = load_settings(config_path=config)
+    except ConfigurationError as exc:
+        typer.echo(f"Error: {exc.message} ({exc.code})", err=True)
+        raise typer.Exit(3) from exc
+
+    dumped = loaded.settings.model_dump(mode="json")
+    if json_output:
+        typer.echo(
+            json.dumps(
+                {
+                    "values": dumped,
+                    "sources": loaded.sources,
+                    "config_path": str(loaded.config_path),
+                }
+            )
+        )
+        return
+
+    typer.echo(
+        f"# {loaded.config_path}{'' if loaded.config_file_used else ' (not found; defaults apply)'}"
+    )
+    for section, fields in dumped.items():
+        for field_name, value in fields.items():
+            path = f"{section}.{field_name}"
+            source = loaded.sources.get(path, "default")
+            rendered = "********" if _looks_secret(field_name) else value
+            typer.echo(f"{path:<40} {rendered!s:<24} ({source})")
+
+
+@app.command("validate")
+def validate(
+    config: Annotated[
+        str | None, typer.Option("--config", help="Path to a config.toml file.")
+    ] = None,
+) -> None:
+    """Validate configuration without starting the service. Exit 0 or 3.
+
+    Example:
+        loadcoach config validate --config ./config.toml
+    """
+    from loadcoach.config import ConfigurationError, load_settings
+
+    try:
+        load_settings(config_path=config)
+    except ConfigurationError as exc:
+        typer.echo(f"Error: {exc.message} ({exc.code})", err=True)
+        raise typer.Exit(3) from exc
+    typer.echo("Configuration is valid.")
+
+
+@app.command("path")
+def path(
+    config: Annotated[
+        str | None, typer.Option("--config", help="Path to a config.toml file.")
+    ] = None,
+) -> None:
+    """Print the resolved configuration file location.
+
+    Example:
+        loadcoach config path
+    """
+    from loadcoach.config import resolve_config_path
+
+    typer.echo(str(resolve_config_path(config)))
+
+
+@app.command("init")
+def init(
+    config: Annotated[
+        str | None, typer.Option("--config", help="Path to write the config file to.")
+    ] = None,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite an existing file.")] = False,
+) -> None:
+    """Write a fully commented example configuration file.
+
+    Example:
+        loadcoach config init --force
+    """
+    from loadcoach.config import EXAMPLE_CONFIG_TOML, resolve_config_path
+
+    target = resolve_config_path(config)
+    if target.exists() and not force:
+        typer.echo(f"Error: {target} already exists (use --force to overwrite).", err=True)
+        raise typer.Exit(3)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(EXAMPLE_CONFIG_TOML, encoding="utf-8")
+    typer.echo(str(target))
+
+
+@app.command("reference")
+def reference(
+    check: Annotated[
+        bool,
+        typer.Option(
+            "--check", help="Exit 1 if docs/configuration.md differs from the generated text."
+        ),
+    ] = False,
+    output: Annotated[
+        str | None, typer.Option("--output", help="Write to this file instead of stdout.")
+    ] = None,
+) -> None:
+    """Generate the configuration reference from the settings model (configuration standards §8).
+
+    Mode: local. With ``--check``, compares against ``--output`` (or ``docs/configuration.md``)
+    and exits 1 on drift, which is what CI runs.
+    """
+    from pathlib import Path
+
+    from loadcoach.services.config_reference import render_configuration_reference
+
+    rendered = render_configuration_reference()
+    target = Path(output) if output else Path("docs/configuration.md")
+    if check:
+        committed = target.read_text(encoding="utf-8") if target.is_file() else ""
+        if committed != rendered:
+            typer.echo(
+                f"{target} differs from the generated reference; run "
+                "`loadcoach config reference --output docs/configuration.md`",
+                err=True,
+            )
+            raise typer.Exit(1)
+        typer.echo(f"{target} matches the settings model")
+        return
+    if output:
+        target.write_text(rendered, encoding="utf-8")
+        typer.echo(f"wrote {target}")
+    else:
+        typer.echo(rendered)

loadcoach/cli/commands/db.py

@@ -0,0 +1,249 @@
+"""loadcoach.cli.commands.db — upgrade, status, backup, restore.
+
+Every command here is **local** mode (CLI standards §6): it runs the service layer in-process
+against the configured database and needs no server running. Only ``typer`` and ``json`` load at
+module level, so registering this subgroup never pulls in SQLAlchemy or Alembic
+(CLI standards §12).
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+
+if TYPE_CHECKING:
+    from loadcoach.config import StorageSettings
+    from loadcoach.services.database import Database
+
+__all__ = ["app"]
+
+app = typer.Typer(help="Database migration and maintenance.")
+
+
+@contextmanager
+def _open_database(config: str | None) -> Iterator[tuple[Database, StorageSettings]]:
+    """Resolve configuration and open one database handle for this command, or exit 3.
+
+    One handle per command, closed on the way out — the CLI is one-shot, so it neither needs nor
+    wants the server's application-lifetime engine.
+    """
+    from loadcoach.config import ConfigurationError, load_settings
+    from loadcoach.services.database import Database
+
+    try:
+        loaded = load_settings(config_path=config)
+    except ConfigurationError as exc:
+        typer.echo(f"Error: {exc.message} ({exc.code})", err=True)
+        raise typer.Exit(3) from exc
+    storage = loaded.settings.storage
+    if storage.database_url is None:  # pragma: no cover — StorageSettings always fills this in
+        typer.echo("Error: no database_url configured (CONFIGURATION_ERROR)", err=True)
+        raise typer.Exit(3)
+    with Database.from_url(
+        storage.database_url, statement_timeout_ms=storage.statement_timeout_ms
+    ) as database:
+        yield database, storage
+
+
+def _human_bytes(value: int) -> str:
+    """Render a byte count at human scale, exact below 1 KiB."""
+    if value < 1024:
+        return f"{value} B"
+    scaled = float(value)
+    for unit in ("KiB", "MiB", "GiB"):
+        scaled /= 1024
+        if scaled < 1024 or unit == "GiB":
+            return f"{scaled:.1f} {unit}"
+    raise AssertionError("unreachable: the GiB branch always returns")  # pragma: no cover
+
+
+def _fail(exc: Exception) -> typer.Exit:
+    """Print the standard CLI error line and return the exit-4 (dependency unavailable) signal."""
+    code = getattr(exc, "code", "DATABASE_ERROR")
+    typer.echo(f"Error: {exc} ({code})", err=True)
+    return typer.Exit(4)
+
+
+@app.command("upgrade")
+def upgrade(
+    revision: Annotated[str, typer.Argument(help="Target revision.")] = "head",
+    config: Annotated[
+        str | None, typer.Option("--config", help="Path to a config.toml file.")
+    ] = None,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Print JSON instead of text.")
+    ] = False,
+) -> None:
+    """Migrate the database to REVISION. Mode: local. A no-op at the target revision (exit 0).
+
+    Example:
+        loadcoach db upgrade
+    """
+    from weightsdb import DatabaseError
+
+    from loadcoach.services.database import upgrade as upgrade_database
+
+    with _open_database(config) as (database, storage):
+        try:
+            outcome = upgrade_database(
+                database, revision=revision, backup_retention=storage.backup_retention
+            )
+        except DatabaseError as exc:
+            raise _fail(exc) from exc
+
+    if json_output:
+        typer.echo(
+            json.dumps(
+                {
+                    "from_revision": outcome.from_revision,
+                    "to_revision": outcome.to_revision,
+                    "backed_up": outcome.backed_up,
+                    "backup_path": str(outcome.backup_path) if outcome.backup_path else None,
+                    "pruned_backups": [str(path) for path in outcome.pruned_backups],
+                    "restore_on_failure_available": outcome.restore_on_failure_available,
+                }
+            )
+        )
+    else:
+        typer.echo(f"{outcome.from_revision or '(empty)'} -> {outcome.to_revision}")
+        if outcome.backed_up:
+            typer.echo(f"Backup written to {outcome.backup_path}")
+        for path in outcome.pruned_backups:
+            typer.echo(f"Rotated out old backup {path}")
+
+
+@app.command("status")
+def status(
+    config: Annotated[
+        str | None, typer.Option("--config", help="Path to a config.toml file.")
+    ] = None,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Print JSON instead of a table.")
+    ] = False,
+) -> None:
+    """Report revision, table row counts and integrity status. Mode: local.
+
+    Example:
+        loadcoach db status --json
+    """
+    from weightsdb import DatabaseError
+
+    from loadcoach.services.database import get_status
+
+    with _open_database(config) as (database, _):
+        try:
+            report = get_status(database)
+        except DatabaseError as exc:
+            raise _fail(exc) from exc
+
+    if json_output:
+        typer.echo(
+            json.dumps(
+                {
+                    "dialect": report.dialect,
+                    "current_revision": report.current_revision,
+                    "head_revision": report.head_revision,
+                    "is_at_head": report.is_at_head,
+                    "table_row_counts": report.table_row_counts,
+                    "size_bytes": report.size_bytes,
+                    "integrity_ok": report.integrity_ok,
+                    "integrity_detail": report.integrity_detail,
+                }
+            )
+        )
+        return
+    typer.echo(f"dialect:       {report.dialect}")
+    typer.echo(
+        f"revision:      {report.current_revision or '(none)'} (head: {report.head_revision})"
+    )
+    typer.echo(f"at head:       {report.is_at_head}")
+    typer.echo(f"size:          {_human_bytes(report.size_bytes)}")
+    typer.echo(f"integrity:     {'ok' if report.integrity_ok else report.integrity_detail}")
+    for table, count in sorted(report.table_row_counts.items()):
+        typer.echo(f"  {table:<24} {count}")
+
+
+@app.command("backup")
+def backup(
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="Backup destination.")
+    ] = None,
+    config: Annotated[
+        str | None, typer.Option("--config", help="Path to a config.toml file.")
+    ] = None,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Print JSON instead of text.")
+    ] = False,
+) -> None:
+    """Take a consistent backup of the database. Mode: local.
+
+    Example:
+        loadcoach db backup --output ./loadcoach-before-upgrade.sqlite3
+    """
+    from weightsdb import DatabaseError
+
+    from loadcoach.services.database import backup_database
+
+    with _open_database(config) as (database, storage):
+        try:
+            result = backup_database(database, output=output, keep=storage.backup_retention)
+        except DatabaseError as exc:
+            raise _fail(exc) from exc
+
+    if json_output:
+        typer.echo(
+            json.dumps(
+                {
+                    "path": str(result.path),
+                    "size_bytes": result.size_bytes,
+                    "created_at": result.created_at.isoformat(),
+                    "dialect": result.dialect,
+                    "pruned": [str(path) for path in result.pruned],
+                }
+            )
+        )
+    else:
+        typer.echo(str(result.path))
+        for path in result.pruned:
+            typer.echo(f"Rotated out old backup {path}")
+
+
+@app.command("restore")
+def restore(
+    source: Annotated[Path, typer.Argument(help="Backup file to restore from.")],
+    yes: Annotated[
+        bool, typer.Option("--yes", "-y", help="Confirm the restore; required, non-interactive.")
+    ] = False,
+    config: Annotated[
+        str | None, typer.Option("--config", help="Path to a config.toml file.")
+    ] = None,
+) -> None:
+    """Restore the database from SOURCE, overwriting the current one. Mode: local.
+
+    Requires ``--yes``: there is no interactive prompt (CLI standards §5), and refusing without it
+    is exit 2 naming the flag that would have answered it.
+
+    Example:
+        loadcoach db restore ./backups/loadcoach-0001-20260829T090000Z.sqlite3 --yes
+    """
+    from weightsdb import DatabaseError
+
+    from loadcoach.services.database import restore_database
+
+    if not yes:
+        typer.echo("Error: --yes is required to confirm this destructive operation.", err=True)
+        raise typer.Exit(2)
+
+    with _open_database(config) as (database, _):
+        try:
+            result = restore_database(database, source=source, confirm=True)
+        except DatabaseError as exc:
+            raise _fail(exc) from exc
+    typer.echo(
+        f"Restored {result.path} from {result.source} (revision {result.revision or '(none)'})"
+    )