karni-cli 0.3.1__py3-none-any.whl

karni_cli/commands/seed.py

@@ -0,0 +1,34 @@
+"""``karni seed`` — realistic, deterministic demo data (``manage.py karni_seed``)."""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.project import require_project
+
+
+def seed(
+    args: list[str] | None = typer.Argument(
+        None,
+        help="Passed to manage.py karni_seed: --count N, --seed S, --reset, --model app.Model, "
+        "--json, --force.",
+    ),
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+) -> None:
+    """Fill every model with realistic demo data — wraps `manage.py karni_seed [ARGS]`.
+
+    Values come from field names and types (an `email` gets an email,
+    `price` money, `starts_at` a near-future date); relations point at
+    seeded rows; the same --seed gives the same rows. Prints a demo login
+    (demo@example.com / karni-password). Per-model overrides live in
+    <app>/seeds.py (`karni make seeder <Model>`).
+
+    Example: karni seed --count 20 --seed 42 --reset
+    """
+    project = require_project()
+    proc = project_mod.run_manage(
+        project, ["karni_seed", *(args or [])], docker=docker, service=service, capture=False
+    )
+    raise typer.Exit(proc.returncode)

karni_cli/commands/serve.py

@@ -0,0 +1,50 @@
+"""``karni serve`` — start the development stack.
+
+Default: ``docker compose up`` in the project (the scaffold's compose file
+runs django, worker, beat, db, redis and the frontend). ``--local`` instead
+runs ``manage.py runserver`` through the project's ``.venv`` — no Docker.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.project import CliError, require_project
+
+
+def serve(
+    local: bool = typer.Option(
+        False, "--local", help="Run manage.py runserver through the project .venv instead."
+    ),
+    host: str | None = typer.Option(None, "--host", help="--local only. Default 127.0.0.1."),
+    port: int | None = typer.Option(None, "--port", help="--local only. Default 8000."),
+    build: bool = typer.Option(False, "--build", help="compose only: rebuild images first."),
+    detach: bool = typer.Option(False, "--detach", "-d", help="compose only: run in background."),
+) -> None:
+    """Start the dev stack — wraps `docker compose up` (or `manage.py runserver` with --local)."""
+    project = require_project()
+    if local:
+        if build or detach:
+            raise CliError(
+                "--build/--detach apply to docker compose; drop them or drop --local.", code="C004"
+            )
+        if project_mod.venv_python(project) is None:
+            raise CliError(
+                "karni serve --local needs the project's .venv "
+                "(uv venv && uv pip install -r pyproject.toml).\n"
+                "Without one, drop --local to run the docker compose stack.",
+                code="C002",
+            )
+        addrport = f"{host or '127.0.0.1'}:{port or 8000}"
+        proc = project_mod.run_manage(project, ["runserver", addrport], docker=False, capture=False)
+    else:
+        if host is not None or port is not None:
+            raise CliError(
+                "--host/--port need --local; under docker compose the port is set in "
+                "docker-compose.yml (8000).",
+                code="C004",
+            )
+        args = ["up", *(["--build"] if build else []), *(["--detach"] if detach else [])]
+        proc = project_mod.run_compose(project, args)
+    raise typer.Exit(proc.returncode)

karni_cli/commands/shell.py

@@ -0,0 +1,28 @@
+"""``karni shell`` — an interactive Django shell in the project environment."""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.project import require_project
+
+
+def shell(
+    args: list[str] | None = typer.Argument(
+        None, help="Passed to manage.py shell: -c CODE, -i ipython …"
+    ),
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+) -> None:
+    """Open a Django shell — wraps `manage.py shell [ARGS]`."""
+    project = require_project()
+    proc = project_mod.run_manage(
+        project,
+        ["shell", *(args or [])],
+        docker=docker,
+        service=service,
+        capture=False,
+        interactive=True,
+    )
+    raise typer.Exit(proc.returncode)

karni_cli/commands/sync_roles.py

@@ -0,0 +1,32 @@
+"""``karni sync-roles`` — reconcile the role tables with ``KARNI_ROLES`` (``manage.py karni_sync_roles``)."""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.project import require_project
+
+
+def sync_roles(
+    args: list[str] | None = typer.Argument(
+        None, help="Passed to manage.py karni_sync_roles: --dry-run, --json."
+    ),
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+) -> None:
+    """Create or update the roles KARNI_ROLES declares — wraps `manage.py karni_sync_roles [ARGS]`.
+
+    Expands each role's grant patterns against every model and action into
+    Role, Permission and RolePermission rows: creates what is missing,
+    updates what changed, reports roles the database holds that the
+    declaration no longer names, and never deletes. The same sync runs
+    after every `karni migrate` (KARNI_ROLES_AUTOSYNC).
+
+    Example: karni sync-roles --dry-run
+    """
+    project = require_project()
+    proc = project_mod.run_manage(
+        project, ["karni_sync_roles", *(args or [])], docker=docker, service=service, capture=False
+    )
+    raise typer.Exit(proc.returncode)

karni_cli/commands/types.py

@@ -0,0 +1,72 @@
+"""``karni types`` — OpenAPI schema → TS types + typed hooks."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.project import CliError, require_project
+from karni_cli.typegen import write_hooks
+
+_FORMATS = {".yml": "openapi", ".yaml": "openapi", ".json": "openapi-json"}
+
+
+def _openapi_typescript_cmd(project: Path, schema: Path, out: Path) -> list[str]:
+    """Project-pinned binary first; pinned-major npx fallback (E2)."""
+    local = project / "frontend" / "node_modules" / ".bin" / "openapi-typescript"
+    if local.exists():
+        return [str(local), str(schema), "-o", str(out)]
+    return ["npx", "--yes", "openapi-typescript@^7", str(schema), "-o", str(out)]
+
+
+def types(
+    schema_out: Path = typer.Option(Path("frontend/src/api/schema.yml"), "--schema-out"),
+    out: Path = typer.Option(Path("frontend/src/api"), "--out"),
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+) -> None:
+    project = require_project()
+    fmt = _FORMATS.get(schema_out.suffix)
+    if fmt is None:
+        raise CliError(
+            f"--schema-out must end in .yml/.yaml/.json, got {schema_out.suffix}", code="C106"
+        )
+
+    (project / schema_out).parent.mkdir(parents=True, exist_ok=True)
+    proc = project_mod.run_manage(
+        project,
+        ["spectacular", "--format", fmt, "--file", str(schema_out)],
+        docker=docker,
+        service=service,
+    )
+    if proc.returncode != 0:
+        typer.echo(proc.stderr or proc.stdout, err=True)
+        raise typer.Exit(proc.returncode)
+
+    types_file = project / out / "types.ts"
+    ts = subprocess.run(
+        _openapi_typescript_cmd(project, project / schema_out, types_file),
+        cwd=project,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if ts.returncode != 0:
+        typer.echo(ts.stderr, err=True)
+        raise CliError(
+            "openapi-typescript failed — is Node available? "
+            "Add openapi-typescript to frontend devDependencies to pin it.",
+            code="C006",
+        )
+
+    hooks = write_hooks(project / schema_out, project / out)
+    typer.echo(f"Wrote {types_file} and {hooks}")
+
+    pkg = project / "frontend" / "package.json"
+    if pkg.is_file() and '"@karni/ui"' not in pkg.read_text():
+        typer.echo(
+            "Hint: frontend/package.json lacks @karni/ui — `npm i @karni/ui` to use hooks.ts"
+        )

karni_cli/commands/upgrade.py

@@ -0,0 +1,231 @@
+"""``karni upgrade`` — move a project across Karni versions.
+
+1. Find where the project is: the karni its interpreter has installed
+   (``--from`` overrides), and where it goes: ``--to``, default the newest
+   release in the changelog this karni-cli carries.
+2. Select every recorded breaking change in between, in release order
+   (:func:`karni_cli.upgrades.changelog.select`).
+3. Run their codemods over a scratch copy; ``--dry-run`` prints the diff,
+   otherwise the result is written back all or nothing. Writing needs a
+   clean git tree (``--allow-dirty`` overrides) so the change is reviewable
+   and revertible.
+4. Report what was applied, what needs a person (with each migration note)
+   and what was skipped.
+
+Run it before raising the karni pin. The CLI carries the changelog, so the
+project's old karni is fine.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.project import CliError, require_project, venv_python
+from karni_cli.upgrades import changelog, engine
+from karni_cli.upgrades.codemod import load_codemod
+
+if TYPE_CHECKING:
+    from karni.changelog import Change
+
+
+def _installed_version(project: Path, docker: bool | None, service: str) -> str:
+    code = "import karni; print(karni.__version__)"
+    mode = project_mod.resolve_execution(project, docker, service)
+    if mode == "venv":
+        cmd = [str(venv_python(project)), "-c", code]
+    else:
+        cmd = ["docker", "compose", "exec", "-T", service, "python", "-c", code]
+    proc = subprocess.run(cmd, cwd=project, text=True, capture_output=True, check=False)
+    if proc.returncode != 0:
+        raise CliError(
+            "Could not determine the installed karni version "
+            f"(exit {proc.returncode}): {proc.stderr.strip()}\n"
+            "Pass it instead: karni upgrade --from <version>",
+            code="C009",
+        )
+    return proc.stdout.strip()
+
+
+def _baseline(project: Path) -> str | None:
+    """``[tool.karni] baseline`` from pyproject.toml: the release ``karni new`` generated for.
+
+    A fresh project already follows every change up to that release, whatever
+    karni version its environment happens to hold (a checkout still reports
+    the previous release's number while the next one is in development).
+    """
+    import tomllib
+
+    pyproject = project / "pyproject.toml"
+    if not pyproject.is_file():
+        return None
+    try:
+        data = tomllib.loads(pyproject.read_text())
+    except (tomllib.TOMLDecodeError, OSError):
+        return None
+    value = data.get("tool", {}).get("karni", {}).get("baseline")
+    return str(value) if value else None
+
+
+def _git_status(project: Path) -> list[str] | None:
+    """Uncommitted paths under ``project`` (untracked included); None outside git."""
+    try:
+        inside = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            cwd=project,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return None
+    if inside.returncode != 0 or inside.stdout.strip() != "true":
+        return None
+    status = subprocess.run(
+        ["git", "status", "--porcelain", "--untracked-files=all", "--", "."],
+        cwd=project,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if status.returncode != 0:
+        return None
+    return [line[3:] for line in status.stdout.splitlines() if line.strip()]
+
+
+def _check_tree(project: Path, allow_dirty: bool) -> None:
+    dirty = _git_status(project)
+    if dirty is None:
+        why = (
+            f"{project} is not in a git work tree (or git is not installed). karni upgrade "
+            "rewrites source files in place, and without version control nothing shows "
+            "or undoes what it changed."
+        )
+        if not allow_dirty:
+            raise CliError(
+                f"Refusing to upgrade: {why}\nPreview it with --dry-run, put the project "
+                "under git, or pass --allow-dirty to write anyway.",
+                code="C201",
+            )
+        typer.echo(f"warning: {why} Continuing because of --allow-dirty.", err=True)
+        return
+    if dirty:
+        shown = ", ".join(dirty[:5]) + (f" and {len(dirty) - 5} more" if len(dirty) > 5 else "")
+        why = (
+            f"the git working tree has uncommitted changes ({shown}). karni upgrade rewrites "
+            "files in place; on a clean tree `git diff` shows exactly what it changed and "
+            "`git checkout -- .` undoes it, without mixing its edits with yours."
+        )
+        if not allow_dirty:
+            raise CliError(
+                f"Refusing to upgrade: {why}\nCommit or stash first, preview with --dry-run, "
+                "or pass --allow-dirty.",
+                code="C201",
+            )
+        typer.echo(f"warning: {why} Continuing because of --allow-dirty.", err=True)
+
+
+def _list(changes: list[Change]) -> str:
+    default = changelog.newest_release(changes)
+    lines = [f"Breaking changes this karni-cli knows (default --to: {default}):"]
+    release = None
+    for change in changes:
+        if change.release != release:
+            release = change.release
+            lines.append(f"\n{release}")
+        how = f"codemod {change.codemod}" if change.mechanical else "manual"
+        if not change.mechanical and change.codemod:
+            how += f", detector {change.codemod}"
+        removal = f", removed in {change.removed_in}" if change.removed_in else ""
+        arrow = f" -> {change.replacement}" if change.replacement else ""
+        lines.append(f"  {change.id}  [{change.kind}, {how}{removal}]")
+        lines.append(f"      {change.symbol}{arrow}")
+    return "\n".join(lines)
+
+
+def upgrade(
+    to: str | None = typer.Option(
+        None,
+        "--to",
+        metavar="VERSION",
+        help="Target Karni version (default: the newest release in the changelog)",
+    ),
+    from_version: str | None = typer.Option(
+        None,
+        "--from",
+        metavar="VERSION",
+        help="The project's current Karni version, instead of asking its interpreter "
+        "(use it when the new karni is already installed)",
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Print a unified diff of every change and write nothing"
+    ),
+    allow_dirty: bool = typer.Option(
+        False,
+        "--allow-dirty",
+        help="Write even with uncommitted changes, or outside a git work tree",
+    ),
+    list_only: bool = typer.Option(
+        False, "--list", help="List every recorded breaking change and exit"
+    ),
+    docker: bool | None = typer.Option(
+        None, "--docker/--no-docker", help="Where to ask for the installed karni version"
+    ),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+) -> None:
+    """Upgrade the project's code across Karni versions: codemods plus a report."""
+    changes = changelog.load()
+    if list_only:
+        typer.echo(_list(changes))
+        return
+
+    project = require_project()
+    current = from_version or _installed_version(project, docker, service)
+    target = to or changelog.newest_release(changes)
+    now, then = (
+        changelog.parse(current, "The project's karni version"),
+        changelog.parse(target, "--to"),
+    )
+    baseline = _baseline(project) if from_version is None else None
+    if baseline is not None and changelog.parse(baseline, "[tool.karni] baseline") > now:
+        current, now = baseline, changelog.parse(baseline, "[tool.karni] baseline")
+    if then < now:
+        raise CliError(
+            f"--to {target} is older than the project's karni {current}; "
+            "karni upgrade does not downgrade.",
+            code="C202",
+        )
+    horizon = changelog.horizon(changes)
+    if then > horizon:
+        typer.echo(
+            f"warning: this karni-cli records changes up to {horizon}; any after that are "
+            "not applied. Upgrade karni-cli first (pipx upgrade karni-cli).",
+            err=True,
+        )
+    selected = changelog.select(changes, current, target)
+    if not selected:
+        typer.echo(f"karni {current} -> {target}: no recorded breaking changes. Nothing to do.")
+        return
+    if not dry_run:
+        _check_tree(project, allow_dirty)
+
+    mechanical = sum(1 for change in selected if change.mechanical)
+    typer.echo(
+        f"karni {current} -> {target}: {len(selected)} change(s), {mechanical} mechanical, "
+        f"{len(selected) - mechanical} manual" + (" (dry run)" if dry_run else "")
+    )
+    report = engine.run(
+        project,
+        selected,
+        current=current,
+        target=target,
+        dry_run=dry_run,
+        resolve=load_codemod,
+    )
+    if dry_run and report.changes:
+        typer.echo(report.diff, nl=False)
+    typer.echo(engine.render(report))

karni_cli/commands/worker.py

@@ -0,0 +1,63 @@
+"""``karni worker`` — a Celery worker through the project interpreter.
+
+With the docker compose stack up, a ``worker`` service already runs; this
+command is for local (``.venv``) development or a one-off extra worker.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.project import require_project
+
+
+def celery_args(celery_app: str, role: str, loglevel: str, extra: list[str] | None) -> list[str]:
+    """``-m celery -A <app> <role> -l <level> [extra]`` (shared with ``karni beat``)."""
+    return ["-m", "celery", "-A", celery_app, role, "-l", loglevel, *(extra or [])]
+
+
+def host_pool_args(extra: list[str] | None, platform: str | None = None) -> list[str]:
+    """``--pool=solo`` for a host worker on macOS, unless the caller chose a pool.
+
+    Celery's default prefork pool cannot run tasks on macOS (every task fails
+    in ``fast_trace_task`` with "not enough values to unpack"); the solo pool
+    does, and a development worker needs nothing more. Docker runs Linux and
+    keeps the default.
+    """
+    args = list(extra or [])
+    platform = platform or sys.platform
+    if platform != "darwin" or any(a == "-P" or a.startswith(("--pool", "-P")) for a in args):
+        return args
+    return [*args, "--pool=solo"]
+
+
+def worker(
+    args: list[str] | None = typer.Argument(
+        None, help="Passed to celery worker: -Q QUEUES, --concurrency N …"
+    ),
+    celery_app: str = typer.Option(
+        "config", "--app", "-A", envvar="KARNI_CELERY_APP", help="Celery app module."
+    ),
+    loglevel: str = typer.Option("info", "--loglevel", "-l"),
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+) -> None:
+    """Run a Celery worker — wraps `python -m celery -A config worker -l info [ARGS]`.
+
+    A host worker on macOS gets `--pool=solo` (the prefork pool cannot run tasks there).
+    """
+    project = require_project()
+    on_host = docker is not True and project_mod.venv_python(project) is not None
+    extra = host_pool_args(args) if on_host else list(args or [])
+    proc = project_mod.run_python(
+        project,
+        celery_args(celery_app, "worker", loglevel, extra),
+        docker=docker,
+        service=service,
+        capture=False,
+        interactive=True,
+    )
+    raise typer.Exit(proc.returncode)

karni_cli/config.py

@@ -0,0 +1,142 @@
+"""Karni CLI settings: ``karni config get|set|list``.
+
+Two TOML files, flat ``key = value``:
+
+* project — ``<project>/.karni/config.toml``, committed: applies to the team;
+* global  — ``$XDG_CONFIG_HOME/karni/config.toml`` (default ``~/.config``):
+  applies to every project on this machine.
+
+The project file wins over the global one, which wins over the default.
+Keys are validated against :data:`KEYS`; adding a setting is one entry there.
+Unknown keys in a file are ignored (a newer karni may have written them).
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import tomlkit
+
+from karni_cli.project import CliError
+
+PROJECT_FILE = Path(".karni") / "config.toml"
+
+_TRUE = frozenset({"true", "yes", "on", "1"})
+_FALSE = frozenset({"false", "no", "off", "0"})
+
+
+@dataclass(frozen=True)
+class ConfigKey:
+    name: str
+    default: bool
+    help: str
+
+
+#: Every setting karni reads. Add a setting here; nothing else needs editing.
+KEYS: dict[str, ConfigKey] = {
+    key.name: key
+    for key in (
+        ConfigKey(
+            "suggest_tools",
+            True,
+            "One-time tips about optional tools (karni doctor, karni check outside CI).",
+        ),
+    )
+}
+
+
+@dataclass(frozen=True)
+class Value:
+    key: str
+    value: bool
+    #: "project", "global" or "default".
+    source: str
+    path: Path | None = None
+
+
+def global_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    root = Path(base) if base else Path.home() / ".config"
+    return root / "karni" / "config.toml"
+
+
+def project_path(project: Path) -> Path:
+    return project / PROJECT_FILE
+
+
+def key(name: str) -> ConfigKey:
+    found = KEYS.get(name)
+    if found is None:
+        raise CliError(f"Unknown setting {name!r} (known: {', '.join(sorted(KEYS))}).", code="C007")
+    return found
+
+
+def parse(name: str, raw: str) -> bool:
+    key(name)
+    text = raw.strip().lower()
+    if text in _TRUE:
+        return True
+    if text in _FALSE:
+        return False
+    raise CliError(f"{name} is a boolean: use true or false, got {raw!r}.", code="C007")
+
+
+def render(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def read_file(path: Path) -> dict[str, bool]:
+    """The known settings in ``path`` (missing file = none); bad values name the file."""
+    if not path.is_file():
+        return {}
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise CliError(f"{path}: not valid TOML ({exc}).", code="C007") from None
+    found: dict[str, bool] = {}
+    for name in KEYS:
+        if name not in data:
+            continue
+        if not isinstance(data[name], bool):
+            raise CliError(
+                f"{path}: {name} must be true or false, got {data[name]!r}.", code="C007"
+            )
+        found[name] = data[name]
+    return found
+
+
+def resolve(name: str, project: Path | None, *, global_only: bool = False) -> Value:
+    """The effective value of ``name``: project file, then global file, then default."""
+    spec = key(name)
+    scopes: list[tuple[str, Path]] = []
+    if project is not None and not global_only:
+        scopes.append(("project", project_path(project)))
+    scopes.append(("global", global_path()))
+    for source, path in scopes:
+        values = read_file(path)
+        if name in values:
+            return Value(name, values[name], source, path)
+    return Value(name, spec.default, "default")
+
+
+def write(name: str, value: bool, path: Path) -> None:
+    """Set ``name`` in ``path``, keeping the file's other content and comments."""
+    key(name)
+    try:
+        document: Any = (
+            tomlkit.parse(path.read_text(encoding="utf-8"))
+            if path.is_file()
+            else tomlkit.document()
+        )
+    except Exception as exc:  # noqa: BLE001 - tomlkit raises its own parse errors
+        raise CliError(f"{path}: not valid TOML ({exc}).", code="C007") from None
+    document[name] = value
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(tomlkit.dumps(document), encoding="utf-8")
+    except OSError as exc:
+        raise CliError(f"Cannot write {path}: {exc}", code="C008") from None

karni_cli/environment.py

@@ -0,0 +1,29 @@
+"""Facts about where the CLI is running."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+#: ``CI`` is the de-facto convention; the rest are set by CI systems that do
+#: not always export it (GitHub Actions, GitLab, Buildkite, CircleCI, Jenkins,
+#: Azure Pipelines, TeamCity, Bitbucket Pipelines, AWS CodeBuild).
+CI_ENV_VARS: tuple[str, ...] = (
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "BUILDKITE",
+    "CIRCLECI",
+    "JENKINS_URL",
+    "TF_BUILD",
+    "TEAMCITY_VERSION",
+    "BITBUCKET_BUILD_NUMBER",
+    "CODEBUILD_BUILD_ID",
+)
+_FALSY = frozenset({"", "0", "false", "no", "off"})
+
+
+def is_ci(environ: Mapping[str, str] | None = None) -> bool:
+    """True when any CI variable is set to something other than an explicit false."""
+    env = os.environ if environ is None else environ
+    return any(env.get(name, "").strip().lower() not in _FALSY for name in CI_ENV_VARS)