bad-decisions 1.0.4__py3-none-any.whl

bad_decisions/__init__.py

@@ -0,0 +1,3 @@
+"""Reusable engine and service for fill-in-the-blank party card games."""
+
+__version__ = "1.0.4"

bad_decisions/api.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import logging
+import re
+import time
+import uuid
+from contextlib import asynccontextmanager
+from importlib.resources import files
+from typing import Annotated
+
+from fastapi import FastAPI, Query, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, PlainTextResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from . import __version__
+from .engine import generate_from_resolved
+from .errors import BadDecisionsError
+from .models import Round
+from .packs import Registry, load_registry, resolve_pools
+from .settings import Settings
+
+REQUEST_ID = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+WEB_ASSETS = {"index.html": "text/html; charset=utf-8", "app.js": "application/javascript; charset=utf-8", "style.css": "text/css; charset=utf-8"}
+
+
+def envelope(code: str, message: str, details: dict | None = None) -> dict:
+    return {"error": {"code": code, "message": message, "details": details or {}}}
+
+
+def create_app() -> FastAPI:
+    settings = Settings.from_env()
+    logging.basicConfig(level=settings.log_level, format="%(asctime)s %(levelname)s %(message)s")
+    logger = logging.getLogger("bad_decisions.api")
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        app.state.registry = load_registry(settings.pack_dir)
+        app.state.ready = True
+        yield
+        app.state.ready = False
+
+    app = FastAPI(title="Bad Decisions API", version=__version__, lifespan=lifespan, root_path=settings.root_path)
+
+    @app.middleware("http")
+    async def request_context(request: Request, call_next):
+        supplied = request.headers.get("x-request-id", "")
+        request_id = supplied if REQUEST_ID.fullmatch(supplied) else uuid.uuid4().hex
+        started = time.monotonic()
+        try:
+            response = await call_next(request)
+        except Exception:
+            logger.exception("unhandled request failure request_id=%s", request_id)
+            response = JSONResponse(envelope("internal_error", "Internal server error", {"request_id": request_id}), status_code=500)
+        response.headers["X-Request-ID"] = request_id
+        logger.info(
+            "request method=%s path=%s status=%s duration_ms=%.2f request_id=%s",
+            request.method,
+            request.url.path,
+            response.status_code,
+            (time.monotonic() - started) * 1000,
+            request_id,
+        )
+        return response
+
+    @app.exception_handler(BadDecisionsError)
+    async def domain_error(_request: Request, exc: BadDecisionsError):
+        return JSONResponse(envelope(exc.code, exc.message, exc.details), status_code=400)
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_error(_request: Request, exc: RequestValidationError):
+        return JSONResponse(envelope("request_validation", "Request validation failed", {"errors": exc.errors()}), status_code=422)
+
+    @app.exception_handler(StarletteHTTPException)
+    async def http_error(_request: Request, exc: StarletteHTTPException):
+        if exc.status_code == 404:
+            return JSONResponse(envelope("path_not_found", "Path not found"), status_code=404)
+        return JSONResponse(envelope("http_error", "HTTP error", {"status": exc.status_code}), status_code=exc.status_code)
+
+    @app.get("/healthz")
+    def health(request: Request):
+        ready = bool(getattr(request.app.state, "ready", False))
+        registry: Registry | None = getattr(request.app.state, "registry", None)
+        return JSONResponse(
+            {"status": "ok" if ready else "unavailable", "version": __version__, "pack_count": len(registry.packs) if registry else 0},
+            status_code=200 if ready else 503,
+        )
+
+    @app.get("/", response_class=PlainTextResponse, include_in_schema=False)
+    def howto():
+        prefix = settings.root_path.rstrip("/")
+        return f"""Bad Decisions API
+
+Reusable service for fill-in-the-blank card games.
+
+Deal a completed hand:
+  GET {prefix}/v1/round
+  GET {prefix}/v1/round?packs=example
+  GET {prefix}/v1/round?black_packs=prompts&white_packs=responses
+
+Inspect the loaded registry:
+  GET {prefix}/v1/packs
+  GET {prefix}/v1/packs/{{pack_id}}
+
+Portable packs:
+  bad-decisions pack validate example.carddeck
+  Format documentation: CARDDECK.md
+
+Service interfaces:
+  Interactive API docs: {prefix}/docs
+  OpenAPI schema: {prefix}/openapi.json
+  Health: {prefix}/healthz
+"""
+
+    def web_asset(name: str):
+        media_type = WEB_ASSETS.get(name)
+        if media_type is None:
+            return JSONResponse(envelope("path_not_found", "Path not found"), status_code=404)
+        return FileResponse(str(files("bad_decisions").joinpath("web", name)), media_type=media_type)
+
+    @app.get("/web", include_in_schema=False)
+    @app.get("/web/", include_in_schema=False)
+    def web_index(request: Request):
+        root_path = request.scope.get("root_path", "").rstrip("/")
+        asset_base = f"{root_path}/web/" or "/web/"
+        document = files("bad_decisions").joinpath("web", "index.html").read_text(encoding="utf-8")
+        return HTMLResponse(document.replace("__WEB_BASE__", asset_base))
+
+    @app.get("/web/{asset:path}", include_in_schema=False)
+    def web_file(asset: str):
+        return web_asset(asset)
+
+    def metadata(pack):
+        result = pack.metadata.model_dump(mode="json")
+        result["counts"] = {"black": len(pack.black), "white": len(pack.white)}
+        return result
+
+    @app.get("/v1/packs")
+    def list_packs(request: Request):
+        return [metadata(pack) for pack in request.app.state.registry.packs.values()]
+
+    @app.get("/v1/packs/{pack_id}")
+    def get_pack(pack_id: str, request: Request):
+        pack = request.app.state.registry.packs.get(pack_id)
+        if pack is None:
+            return JSONResponse(envelope("pack_not_found", f"Pack not found: {pack_id}", {"available_packs": list(request.app.state.registry.ids)}), status_code=404)
+        return metadata(pack)
+
+    @app.get("/v1/round", response_model=Round)
+    def round_endpoint(
+        request: Request,
+        packs: Annotated[str, Query()] = "base",
+        black_packs: Annotated[str | None, Query()] = None,
+        white_packs: Annotated[str | None, Query()] = None,
+    ):
+        allowed = {"packs", "black_packs", "white_packs"}
+        unknown = sorted(set(request.query_params) - allowed)
+        repeated = sorted(key for key in allowed if len(request.query_params.getlist(key)) > 1)
+        if unknown:
+            return JSONResponse(envelope("unknown_query_parameter", "Unknown query parameter", {"parameters": unknown}), status_code=400)
+        if repeated:
+            return JSONResponse(envelope("repeated_query_parameter", "Selector parameters must occur once", {"parameters": repeated}), status_code=400)
+        registry = request.app.state.registry
+        resolved = resolve_pools(registry, packs=packs, black_packs=black_packs, white_packs=white_packs)
+        response = JSONResponse(generate_from_resolved(resolved, registry).model_dump(mode="json"))
+        response.headers["Cache-Control"] = "no-store"
+        return response
+
+    return app

bad_decisions/archive.py

@@ -0,0 +1,199 @@
+"""Portable, offline CardDeck archive support."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+import tempfile
+import zipfile
+from importlib.resources import files
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from .errors import PackConfigurationError
+from .models import ID_PATTERN, Pack
+
+FORMAT = "carddeck"
+FORMAT_VERSION = 1
+CARDDECK_SUFFIX = ".carddeck"
+REQUIRED_MEMBERS = frozenset({"manifest.json", "pack.json", "LICENSE.txt", "ATTRIBUTION.md"})
+MAX_MEMBER_BYTES = 2 * 1024 * 1024
+MAX_ARCHIVE_BYTES = 5 * 1024 * 1024
+MAX_COMPRESSION_RATIO = 100
+
+
+class ArchiveManifest(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    format: str
+    format_version: int
+    pack_id: str = Field(pattern=ID_PATTERN)
+    pack_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+
+
+def _error(message: str) -> PackConfigurationError:
+    return PackConfigurationError(f"carddeck: {message}")
+
+
+def _format_for_path(path: Path) -> str:
+    if path.suffix == CARDDECK_SUFFIX:
+        return FORMAT
+    raise _error("archive filename must end in .carddeck")
+
+
+def _canonical_json(value: object) -> bytes:
+    return (json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n").encode("utf-8")
+
+
+def _pack_payload(pack: Pack) -> bytes:
+    return _canonical_json(pack.model_dump(mode="json"))
+
+
+def _read_archive(path: Path) -> tuple[ArchiveManifest, Pack, bytes, str, str]:
+    expected_format = _format_for_path(path)
+    try:
+        with zipfile.ZipFile(path) as archive:
+            infos = archive.infolist()
+            names = [info.filename for info in infos]
+            if len(infos) != len(REQUIRED_MEMBERS) or set(names) != REQUIRED_MEMBERS:
+                raise _error("archive must contain exactly manifest.json, pack.json, LICENSE.txt, and ATTRIBUTION.md")
+            total = 0
+            for info in infos:
+                if Path(info.filename).name != info.filename or info.is_dir():
+                    raise _error(f"unsafe archive member: {info.filename!r}")
+                if stat.S_ISLNK(info.external_attr >> 16):
+                    raise _error(f"symbolic links are not allowed: {info.filename!r}")
+                if info.file_size > MAX_MEMBER_BYTES:
+                    raise _error(f"archive member is too large: {info.filename!r}")
+                if info.file_size and not info.compress_size:
+                    raise _error(f"invalid compressed member: {info.filename!r}")
+                if info.compress_size and info.file_size / info.compress_size > MAX_COMPRESSION_RATIO:
+                    raise _error(f"archive member compression ratio is too high: {info.filename!r}")
+                total += info.file_size
+            if total > MAX_ARCHIVE_BYTES:
+                raise _error("archive is too large")
+            members = {name: archive.read(name) for name in REQUIRED_MEMBERS}
+    except (OSError, zipfile.BadZipFile, RuntimeError) as exc:
+        raise _error(f"cannot read archive: {exc}") from exc
+
+    try:
+        manifest = ArchiveManifest.model_validate_json(members["manifest.json"])
+    except ValidationError as exc:
+        raise _error(f"invalid manifest: {exc}") from exc
+    if manifest.format != expected_format or manifest.format_version != FORMAT_VERSION:
+        raise _error("unsupported archive format or version")
+    payload = members["pack.json"]
+    if hashlib.sha256(payload).hexdigest() != manifest.pack_sha256:
+        raise _error("pack.json checksum does not match manifest")
+    try:
+        pack = Pack.model_validate_json(payload)
+    except ValidationError as exc:
+        raise _error(f"invalid pack.json: {exc}") from exc
+    if pack.metadata.id != manifest.pack_id:
+        raise _error("manifest pack_id does not match pack metadata")
+    try:
+        license_text = members["LICENSE.txt"].decode("utf-8").strip()
+        attribution = members["ATTRIBUTION.md"].decode("utf-8").strip()
+    except UnicodeDecodeError as exc:
+        raise _error("license and attribution files must be UTF-8") from exc
+    if not license_text or not attribution:
+        raise _error("license and attribution files must not be empty")
+    return manifest, pack, payload, license_text, attribution
+
+
+def validate_archive(path: str | Path) -> Pack:
+    """Validate an archive fully and return its pack without mutating disk."""
+
+    _, pack, _, _, _ = _read_archive(Path(path))
+    return pack
+
+
+def export_pack(pack: Pack, destination: str | Path) -> Path:
+    """Write a deterministic portable archive, refusing an existing target."""
+
+    target = Path(destination)
+    format_name = _format_for_path(target)
+    if target.exists():
+        raise _error(f"destination already exists: {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    payload = _pack_payload(pack)
+    manifest = ArchiveManifest(
+        format=format_name,
+        format_version=FORMAT_VERSION,
+        pack_id=pack.metadata.id,
+        pack_sha256=hashlib.sha256(payload).hexdigest(),
+    )
+    contents = {
+        "manifest.json": _canonical_json(manifest.model_dump()),
+        "pack.json": payload,
+        "LICENSE.txt": (pack.metadata.license_notice.strip() + "\n").encode("utf-8"),
+        "ATTRIBUTION.md": (pack.metadata.attribution.strip() + "\n").encode("utf-8"),
+    }
+    try:
+        with zipfile.ZipFile(target, "x", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as archive:
+            for name in sorted(contents):
+                info = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0))
+                info.compress_type = zipfile.ZIP_DEFLATED
+                info.external_attr = 0o100644 << 16
+                archive.writestr(info, contents[name])
+    except (OSError, zipfile.BadZipFile) as exc:
+        raise _error(f"cannot create archive: {exc}") from exc
+    return target
+
+
+def import_pack(archive_path: str | Path, registry_dir: str | Path) -> Path:
+    """Atomically install an archive's JSON pack into an absolute registry directory."""
+
+    _, pack, payload, _, _ = _read_archive(Path(archive_path))
+    destination_dir = Path(registry_dir)
+    if not destination_dir.is_absolute():
+        raise _error("registry directory must be an absolute path")
+    destination_dir.mkdir(parents=True, exist_ok=True)
+    if not destination_dir.is_dir():
+        raise _error(f"registry path is not a directory: {destination_dir}")
+    destination = destination_dir / f"{pack.metadata.id}.json"
+    if destination.exists():
+        raise _error(f"refusing to overwrite existing pack: {destination}")
+    try:
+        with tempfile.NamedTemporaryFile("wb", dir=destination_dir, prefix=".carddeck-", delete=False) as handle:
+            temporary = Path(handle.name)
+            handle.write(payload)
+        os.chmod(temporary, 0o644)
+        os.replace(temporary, destination)
+    except OSError as exc:
+        try:
+            temporary.unlink(missing_ok=True)
+        except UnboundLocalError:
+            pass
+        raise _error(f"cannot import pack: {exc}") from exc
+    return destination
+
+
+def initialize_registry(registry_dir: str | Path) -> tuple[Path, ...]:
+    """Create an empty absolute registry directory populated with bundled packs."""
+
+    destination_dir = Path(registry_dir)
+    if not destination_dir.is_absolute():
+        raise _error("registry directory must be an absolute path")
+    destination_dir.mkdir(parents=True, exist_ok=True)
+    if not destination_dir.is_dir():
+        raise _error(f"registry path is not a directory: {destination_dir}")
+    if any(destination_dir.iterdir()):
+        raise _error(f"refusing to initialize non-empty registry: {destination_dir}")
+    source_dir = files("bad_decisions").joinpath("data/packs")
+    copied: list[Path] = []
+    try:
+        for source in sorted(source_dir.iterdir(), key=lambda item: item.name):
+            if source.name.endswith(".json"):
+                target = destination_dir / source.name
+                target.write_bytes(source.read_bytes())
+                os.chmod(target, 0o644)
+                copied.append(target)
+    except OSError as exc:
+        raise _error(f"cannot initialize registry: {exc}") from exc
+    if not copied:
+        raise _error("no bundled pack files found")
+    return tuple(copied)

bad_decisions/cli.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import argparse
+import math
+import signal
+import sys
+import time
+from pathlib import Path
+from typing import Sequence
+
+from .archive import export_pack, import_pack, initialize_registry, validate_archive
+from .engine import generate_from_resolved, render_round
+from .errors import BadDecisionsError, PackConfigurationError, UnknownPackError
+from .packs import load_registry, resolve_pools
+from . import operations
+
+
+class CliArgumentError(ValueError):
+    pass
+
+
+def positive_finite(value: str) -> float:
+    try:
+        number = float(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be a number") from exc
+    if not math.isfinite(number) or number <= 0:
+        raise argparse.ArgumentTypeError("must be finite and greater than zero")
+    return number
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(description="Deal hands and manage a Bad Decisions service.")
+    mode = result.add_mutually_exclusive_group()
+    mode.add_argument("--oneshot", action="store_true", help="print one rendered round and exit")
+    mode.add_argument("--rapid", action="store_true", help="continuously print completed rounds")
+    result.add_argument("--delay", type=positive_finite, help="positive seconds between rapid rounds (default: 1.0)")
+    result.add_argument("--packs", default="base", help="comma-separated pack IDs for both colors (default: base)")
+    result.add_argument("--black-packs", help="override the black-card selector")
+    result.add_argument("--white-packs", help="override the white-card selector")
+    result.add_argument("--list-packs", action="store_true", help="list available packs and exit")
+    return result
+
+
+def pack_parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(prog="bad-decisions pack", description="Validate, export, or import portable .carddeck archives.")
+    commands = result.add_subparsers(dest="command", required=True)
+    validate = commands.add_parser("validate", help="validate an archive without changing disk")
+    validate.add_argument("archive", type=Path)
+    export = commands.add_parser("export", help="export one registered pack to an archive")
+    export.add_argument("pack_id")
+    export.add_argument("archive", type=Path)
+    imported = commands.add_parser("import", help="import an archive into an absolute pack registry directory")
+    imported.add_argument("archive", type=Path)
+    imported.add_argument("registry_dir", type=Path)
+    initialized = commands.add_parser("init-registry", help="initialize an empty absolute registry with bundled packs")
+    initialized.add_argument("registry_dir", type=Path)
+    return result
+
+
+def _write(text: str = "", *, stream=sys.stdout, flush: bool = False) -> None:
+    print(text, file=stream, flush=flush)
+
+
+def _interactive(resolved, registry) -> int:
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        _write("Interactive mode requires a terminal; use --oneshot or --rapid.", stream=sys.stderr)
+        return 2
+    while True:
+        generated = generate_from_resolved(resolved, registry)
+        _write()
+        _write("═" * 72)
+        _write(generated.black.repr)
+        try:
+            command = input("\nPress Enter to reveal, or q to quit: ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            _write()
+            return 0
+        if command == "q":
+            return 0
+        _write()
+        for answer in generated.white:
+            _write(f"⬜ {answer.text}")
+        _write(f"\n→ {generated.result}")
+        try:
+            command = input("\nPress Enter for another round, or q to quit: ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            _write()
+            return 0
+        if command == "q":
+            return 0
+
+
+def _run_pack(argv: Sequence[str]) -> int:
+    args = pack_parser().parse_args(argv)
+    if args.command == "validate":
+        pack = validate_archive(args.archive)
+        _write(f"valid carddeck: {pack.metadata.id}")
+        return 0
+    if args.command == "export":
+        registry = load_registry()
+        if args.pack_id not in registry.packs:
+            raise UnknownPackError(f"Unknown pack: {args.pack_id}", {"available_packs": list(registry.ids)})
+        target = export_pack(registry.packs[args.pack_id], args.archive)
+        _write(f"exported {args.pack_id} to {target}")
+        return 0
+    if args.command == "init-registry":
+        copied = initialize_registry(args.registry_dir)
+        _write(f"initialized registry with {len(copied)} bundled packs at {args.registry_dir}")
+        return 0
+    target = import_pack(args.archive, args.registry_dir)
+    _write(f"imported {target.stem} to {target}")
+    return 0
+
+
+def run(argv: Sequence[str] | None = None, *, sleep=time.sleep) -> int:
+    values = list(sys.argv[1:] if argv is None else argv)
+    if values and values[0] in {"setup", "serve", "deploy", "status", "reload", "stop"}:
+        return operations.run(values)
+    if values and values[0] == "pack":
+        return _run_pack(values[1:])
+    args = parser().parse_args(values)
+    if args.delay is not None and not args.rapid:
+        parser().error("--delay may only be used with --rapid")
+    registry = load_registry()
+    if args.list_packs:
+        for pack_id, pack in registry.packs.items():
+            _write(f"{pack_id}\t{pack.metadata.name}\tblack={len(pack.black)}\twhite={len(pack.white)}")
+        return 0
+    resolved = resolve_pools(registry, packs=args.packs, black_packs=args.black_packs, white_packs=args.white_packs)
+    if args.oneshot:
+        _write(generate_from_resolved(resolved, registry).result)
+        return 0
+    if args.rapid:
+        delay = args.delay if args.delay is not None else 1.0
+        while True:
+            _write(generate_from_resolved(resolved, registry).result, flush=True)
+            sleep(delay)
+    return _interactive(resolved, registry)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+    try:
+        return run(argv)
+    except KeyboardInterrupt:
+        return 0
+    except PackConfigurationError as exc:
+        _write(f"configuration error: {exc.message}", stream=sys.stderr)
+        return 1
+    except BadDecisionsError as exc:
+        _write(f"{exc.code}: {exc.message}", stream=sys.stderr)
+        return 2
+    except BrokenPipeError:
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())