base-cli 0.1.0__py3-none-any.whl

base_cli/logging.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import sys
+import time
+from pathlib import Path
+from typing import TextIO
+
+from .context import get_current_context
+from .paths import current_working_dir
+from .redaction import redact_argv
+
+_COLOR_RESET = "\033[0m"
+_LEVEL_COLORS = {
+    logging.DEBUG: "\033[0;36m",
+    logging.INFO: "\033[0;32m",
+    logging.WARNING: "\033[0;33m",
+    logging.ERROR: "\033[0;31m",
+    logging.CRITICAL: "\033[0;31m",
+}
+
+
+# pylint: disable=too-many-arguments
+def configure_logger(
+    cli_name: str,
+    log_file: Path | None,
+    debug: bool,
+    *,
+    quiet: bool = False,
+    stream: TextIO | None = None,
+    formatter: logging.Formatter | None = None,
+) -> logging.Logger:
+    logger = logging.getLogger(f"base_cli.{cli_name}")
+    logger.setLevel(logging.DEBUG)
+    logger.propagate = False
+    for handler in list(logger.handlers):
+        handler.close()
+        logger.removeHandler(handler)
+
+    user_stream = stream if stream is not None else sys.stderr
+    user_handler = logging.StreamHandler(user_stream)
+    user_handler.setLevel(_user_stream_level(debug, quiet))
+    user_handler.setFormatter(_handler_formatter(formatter, use_color=_use_color(user_stream)))
+    logger.addHandler(user_handler)
+
+    if log_file is not None:
+        file_handler = SecureLogFileHandler(log_file, encoding="utf-8")
+        file_handler.setLevel(logging.DEBUG)
+        file_handler.setFormatter(_handler_formatter(formatter, use_color=False))
+        logger.addHandler(file_handler)
+    return logger
+
+
+def _user_stream_level(debug: bool, quiet: bool) -> int:
+    if quiet:
+        return logging.WARNING
+    if debug:
+        return logging.DEBUG
+    return logging.INFO
+
+
+def _handler_formatter(formatter: logging.Formatter | None, *, use_color: bool) -> logging.Formatter:
+    if formatter is not None:
+        return formatter
+    return BaseCliFormatter(use_color=use_color)
+
+
+def _use_color(stream: TextIO) -> bool:
+    return (
+        os.environ.get("BASE_CLI_COLOR") == "1"
+        and "NO_COLOR" not in os.environ
+        and hasattr(stream, "isatty")
+        and stream.isatty()
+    )
+
+
+def secure_log_file_permissions(log_file: Path) -> None:
+    log_file.chmod(0o600)
+
+
+class SecureLogFileHandler(logging.FileHandler):
+    def _open(self) -> TextIO:
+        fd = os.open(self.baseFilename, _secure_log_file_open_flags(self.mode), 0o600)
+        try:
+            fchmod = getattr(os, "fchmod", None)
+            if fchmod is not None:
+                fchmod(fd, 0o600)
+            return open(fd, self.mode, encoding=self.encoding, errors=self.errors, closefd=True)
+        except BaseException:
+            os.close(fd)
+            raise
+
+
+def _secure_log_file_open_flags(mode: str) -> int:
+    flags = os.O_CREAT
+    if "x" in mode:
+        return flags | os.O_EXCL | os.O_WRONLY
+    if "w" in mode:
+        return flags | os.O_TRUNC | os.O_WRONLY
+    return flags | os.O_APPEND | os.O_WRONLY
+
+
+class BaseCliFormatter(logging.Formatter):
+    def __init__(self, *, use_utc: bool | None = None, use_color: bool = False) -> None:
+        self.use_utc = use_utc if use_utc is not None else os.environ.get("LOG_UTC") == "1"
+        self.use_color = use_color
+        datefmt = "%Y-%m-%d %H:%M:%S UTC" if self.use_utc else "%Y-%m-%d %H:%M:%S %z"
+        super().__init__(datefmt=datefmt)
+        self.converter = time.gmtime if self.use_utc else time.localtime
+
+    def format(self, record: logging.LogRecord) -> str:
+        timestamp = self.formatTime(record, self.datefmt)
+        source = _source_path(record)
+        level = _level_name(record)
+        line = f"{timestamp} {level:<7} {source}:{record.lineno} {record.getMessage()}"
+        if not self.use_color:
+            return line
+        color = _LEVEL_COLORS.get(record.levelno)
+        return f"{color}{line}{_COLOR_RESET}" if color else line
+
+
+def _level_name(record: logging.LogRecord) -> str:
+    if record.levelno == logging.WARNING:
+        return "WARN"
+    if record.levelno == logging.CRITICAL:
+        return "FATAL"
+    return record.levelname
+
+
+def _source_path(record: logging.LogRecord) -> str:
+    path = Path(record.pathname)
+    candidates = []
+    base_home = os.environ.get("BASE_HOME")
+    if base_home:
+        candidates.append(Path(base_home))
+    project_root = _active_project_root()
+    if project_root is not None:
+        candidates.append(project_root)
+    candidates.append(current_working_dir())
+
+    for root in candidates:
+        try:
+            return str(path.resolve().relative_to(root.resolve()))
+        except ValueError:
+            continue
+    return str(path.resolve())
+
+
+def _active_project_root() -> Path | None:
+    try:
+        context = get_current_context()
+    except RuntimeError:
+        return None
+    return context.project_root
+
+
+def log_invocation(logger: logging.Logger, argv: list[str], sensitive_options: set[str]) -> None:
+    logger.debug("argv=%s", redact_argv(argv, sensitive_options))
+    logger.debug("platform=%s %s", platform.system(), platform.machine())
+    logger.debug("python=%s", sys.version.replace("\n", " "))
+
+
+def log_debug(message: str, *args: object) -> None:
+    get_current_context().log.debug(message, *args, stacklevel=2)
+
+
+def log_info(message: str, *args: object) -> None:
+    get_current_context().log.info(message, *args, stacklevel=2)
+
+
+def log_warning(message: str, *args: object) -> None:
+    get_current_context().log.warning(message, *args, stacklevel=2)
+
+
+def log_error(message: str, *args: object) -> None:
+    get_current_context().log.error(message, *args, stacklevel=2)
+
+
+def log_critical(message: str, *args: object) -> None:
+    get_current_context().log.critical(message, *args, stacklevel=2)

base_cli/output.py

@@ -0,0 +1,202 @@
+"""Shared output-format resolution and rendering for Base CLIs."""
+
+from __future__ import annotations
+
+import csv
+import json
+import sys
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any, TextIO
+
+
+PUBLIC_OUTPUT_FORMATS = ("text", "csv", "tsv", "yaml", "json")
+
+
+class OutputFormatError(ValueError):
+    """Raised when a public output format is not supported."""
+
+
+def output_format_choices() -> str:
+    """Return the public choices in help/error-message order."""
+
+    return "|".join(PUBLIC_OUTPUT_FORMATS)
+
+
+def is_terminal(stream: TextIO | None = None) -> bool:
+    """Return whether *stream* is an interactive terminal."""
+
+    candidate = stream if stream is not None else sys.stdout
+    try:
+        return bool(candidate.isatty())
+    except (AttributeError, OSError):
+        return False
+
+
+def resolve_output_format(
+    requested: str | None,
+    *,
+    stream: TextIO | None = None,
+) -> str:
+    """Resolve a requested format, making text TTY-aware.
+
+    ``text`` is intentionally a presentation mode rather than a wire format:
+    it renders a table for terminals and tab-delimited rows for redirected or
+    piped output.  Omitting the format follows the same policy.
+    """
+
+    normalized = (requested or "text").lower()
+    if normalized not in PUBLIC_OUTPUT_FORMATS:
+        raise OutputFormatError(
+            f"Unsupported output format '{requested}'. Expected one of: {', '.join(PUBLIC_OUTPUT_FORMATS)}."
+        )
+    if normalized == "text" and not is_terminal(stream):
+        return "tsv"
+    return normalized
+
+
+# pylint: disable=too-many-arguments
+def render_records(
+    records: Iterable[Mapping[str, Any]],
+    *,
+    requested_format: str | None,
+    columns: Sequence[tuple[str, str]],
+    stream: TextIO | None = None,
+    footer: str | None = None,
+    minimum_widths: Sequence[int] | None = None,
+) -> str:
+    """Render records according to the shared public output contract.
+
+    The returned string is also written to *stream* when supplied (or stdout
+    when omitted).  JSON and YAML retain the mapping shape supplied by the
+    caller; delimited formats use the explicit ``columns`` order and never
+    emit a header or footer. ``minimum_widths`` applies only to terminal table
+    columns; values can still expand beyond those widths.
+    """
+
+    target = stream if stream is not None else sys.stdout
+    record_list = [dict(record) for record in records]
+    resolved = resolve_output_format(requested_format, stream=target)
+
+    if resolved in ("csv", "tsv"):
+        delimiter = "," if resolved == "csv" else "\t"
+        writer = csv.writer(target, delimiter=delimiter, lineterminator="\n")
+        for record in record_list:
+            writer.writerow([_cell_value(record.get(key)) for _header, key in columns])
+        return resolved
+
+    if resolved == "json":
+        target.write(json.dumps(record_list, separators=(",", ":")))
+        target.write("\n")
+        return resolved
+
+    if resolved == "yaml":
+        try:
+            import yaml
+        except ImportError as exc:  # pragma: no cover - environment guard
+            raise RuntimeError("PyYAML is required for YAML output.") from exc
+        target.write(yaml.safe_dump(record_list, sort_keys=False, allow_unicode=True))
+        return resolved
+
+    _write_table(target, record_list, columns, footer, minimum_widths)
+    return resolved
+
+
+def render_document(
+    document: Mapping[str, Any],
+    *,
+    requested_format: str | None,
+    records_key: str | None = None,
+    columns: Sequence[tuple[str, str]] | None = None,
+    stream: TextIO | None = None,
+) -> str:
+    """Render a structured report or leave terminal text to its existing renderer.
+
+    Structured formats preserve the complete document.  Delimited output uses
+    the selected record list (or the document itself) and never emits report
+    prose, headers, or footers.  A terminal ``text`` request returns ``text``
+    without writing so the caller can keep its established human report.
+    """
+
+    target = stream if stream is not None else sys.stdout
+    resolved = resolve_output_format(requested_format, stream=target)
+    if resolved == "text":
+        return resolved
+    if resolved == "json":
+        target.write(json.dumps(dict(document), indent=2))
+        target.write("\n")
+        return resolved
+    if resolved == "yaml":
+        try:
+            import yaml
+        except ImportError as exc:  # pragma: no cover - environment guard
+            raise RuntimeError("PyYAML is required for YAML output.") from exc
+        target.write(yaml.safe_dump(dict(document), sort_keys=False, allow_unicode=True))
+        return resolved
+
+    if records_key:
+        candidate = document.get(records_key)
+        if isinstance(candidate, list):
+            records = [record for record in candidate if isinstance(record, Mapping)]
+        else:
+            records = [document]
+    else:
+        records = [document]
+    selected_columns = columns or _document_columns(records)
+    render_records(
+        records,
+        requested_format=resolved,
+        columns=selected_columns,
+        stream=target,
+    )
+    return resolved
+
+
+def _document_columns(records: Sequence[Mapping[str, Any]]) -> list[tuple[str, str]]:
+    if not records:
+        return []
+    return [(str(key).upper(), str(key)) for key in records[0]]
+
+
+def _cell_value(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (Mapping, list, tuple)):
+        return json.dumps(value, separators=(",", ":"))
+    return str(value)
+
+
+def _write_table(
+    stream: TextIO,
+    records: Sequence[Mapping[str, Any]],
+    columns: Sequence[tuple[str, str]],
+    footer: str | None,
+    minimum_widths: Sequence[int] | None,
+) -> None:
+    selected_minimums = minimum_widths or ()
+    if len(selected_minimums) > len(columns):
+        raise ValueError("minimum_widths cannot contain more entries than columns")
+
+    if not records:
+        if footer:
+            stream.write(f"{footer}\n")
+        return
+
+    widths = [
+        max(len(header), selected_minimums[index] if index < len(selected_minimums) else 0)
+        for index, (header, _key) in enumerate(columns)
+    ]
+    rows: list[list[str]] = []
+    for record in records:
+        row = [_cell_value(record.get(key)) for _header, key in columns]
+        rows.append(row)
+        widths = [max(width, len(value)) for width, value in zip(widths, row)]
+
+    stream.write("  ".join(header.ljust(width) for (header, _key), width in zip(columns, widths)).rstrip())
+    stream.write("\n")
+    for row in rows:
+        stream.write("  ".join(value.ljust(width) for value, width in zip(row, widths)).rstrip())
+        stream.write("\n")
+    if footer:
+        stream.write(f"\n{footer}\n")

base_cli/paths.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import hashlib
+import os
+import re
+import sys
+import time
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+
+_WORKING_DIRECTORY_OVERRIDE: contextvars.ContextVar[Path | None] = contextvars.ContextVar(
+    "base_cli_working_directory_override",
+    default=None,
+)
+
+
+def base_state_root(home: Path | None = None) -> Path:
+    return (home or Path.home()) / ".base.d"
+
+
+def base_cache_root(home: Path | None = None) -> Path:
+    value = os.environ.get("BASE_CACHE_DIR")
+    if value:
+        return Path(value).expanduser()
+    root = home or Path.home()
+    if sys.platform == "darwin":
+        return root / "Library" / "Caches" / "base"
+    return root / ".cache" / "base"
+
+
+def current_working_dir() -> Path:
+    return _WORKING_DIRECTORY_OVERRIDE.get() or Path.cwd()
+
+
+@contextlib.contextmanager
+def use_working_dir(path: Path | None) -> Iterator[None]:
+    if path is None:
+        yield
+        return
+
+    token = _WORKING_DIRECTORY_OVERRIDE.set(path.expanduser().resolve())
+    try:
+        yield
+    finally:
+        _WORKING_DIRECTORY_OVERRIDE.reset(token)
+
+
+def make_run_id() -> str:
+    timestamp = time.strftime("%Y%m%dT%H%M%S", time.gmtime())
+    return f"{timestamp}_{uuid.uuid4().hex[:8]}"
+
+
+def normalize_cli_name(name: str) -> str:
+    stem = Path(name).name
+    if "." in stem:
+        stem = stem.rsplit(".", 1)[0]
+    return stem.replace(" ", "-")
+
+
+def normalize_runtime_owner(value: str | None = None) -> str:
+    """Return the runtime owner namespace for a command invocation."""
+    owner = (value or os.environ.get("BASE_CLI_RUNTIME_OWNER") or "base").strip().lower()
+    if owner not in {"base", "project"}:
+        raise ValueError("BASE_CLI_RUNTIME_OWNER must be 'base' or 'project'.")
+    return owner
+
+
+def runtime_project_name(value: str | None = None) -> str | None:
+    name = (value or os.environ.get("BASE_CLI_PROJECT_NAME") or "").strip()
+    return name or None
+
+
+def runtime_project_root(value: Path | str | None = None) -> Path | None:
+    candidate = value or os.environ.get("BASE_CLI_PROJECT_ROOT")
+    if not candidate:
+        return None
+    return Path(candidate).expanduser().resolve()
+
+
+def runtime_slug(value: str, fallback: str = "unnamed") -> str:
+    normalized = re.sub(r"[^a-zA-Z0-9._-]+", "-", value.strip()).strip(".-_").lower()
+    return normalized or fallback
+
+
+def runtime_run_directory_name(run_id: str, cli_name: str, project_name: str | None = None) -> str:
+    """Return a readable bundle directory name without changing the canonical run ID."""
+    labels = [runtime_slug(cli_name, fallback="run")]
+    if project_name:
+        labels.append(runtime_slug(project_name))
+    return f"{run_id}__{'__'.join(labels)}"
+
+
+def checkout_id(project_root: Path | None) -> str | None:
+    if project_root is None:
+        return None
+    digest = hashlib.sha256(str(project_root.expanduser().resolve()).encode("utf-8")).hexdigest()
+    return digest[:12]
+
+
+def runtime_owner_root(
+    cache_root: Path,
+    owner: str = "base",
+    project_name: str | None = None,
+    project_root: Path | None = None,
+) -> Path:
+    normalized_owner = normalize_runtime_owner(owner)
+    if normalized_owner == "base":
+        return cache_root / "base"
+
+    name = runtime_slug(project_name or "unnamed")
+    checkout = checkout_id(project_root) or "unknown"
+    return cache_root / "projects" / name / checkout
+
+
+def discover_manifest(start: Path) -> Path | None:
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+
+    while True:
+        candidate = current / "base_manifest.yaml"
+        if candidate.is_file():
+            return candidate
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def resolve_base_home() -> Path | None:
+    value = os.environ.get("BASE_HOME")
+    if not value:
+        return None
+    return Path(value).expanduser().resolve()

base_cli/redaction.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import re
+
+REDACTED = "[REDACTED]"
+SECRET_KEY_RE = re.compile(r"(token|password|secret|api[-_]?key|authorization)", re.IGNORECASE)
+URL_CREDENTIALS_RE = re.compile(r"(?P<prefix>[a-zA-Z][a-zA-Z0-9+.-]*://)[^/@\s]+@")
+
+
+def option_name_to_parameter(param_decl: str) -> str:
+    name = param_decl.lstrip("-")
+    return name.replace("-", "_")
+
+
+def parameter_name_from_decls(param_decls: tuple[str, ...]) -> str:
+    options = [decl for decl in param_decls if decl.startswith("--")]
+    if options:
+        return option_name_to_parameter(options[0])
+    return option_name_to_parameter(param_decls[0])
+
+
+def redact_argv(argv: list[str], sensitive_options: set[str]) -> list[str]:
+    redacted: list[str] = []
+    skip_next = False
+    for arg in argv:
+        if skip_next:
+            redacted.append(REDACTED)
+            skip_next = False
+            continue
+
+        option, separator, _value = arg.partition("=")
+        normalized = option_name_to_parameter(option) if option.startswith("--") else option
+        if option.startswith("--") and normalized in sensitive_options:
+            if separator:
+                redacted.append(f"{option}={REDACTED}")
+            else:
+                redacted.append(option)
+                skip_next = True
+            continue
+
+        redacted.append(arg)
+    return redacted
+
+
+def is_secret_key(value: str) -> bool:
+    return SECRET_KEY_RE.search(value) is not None
+
+
+def redact_text_value(value: str) -> str:
+    return URL_CREDENTIALS_RE.sub(lambda match: f"{match.group('prefix')}{REDACTED}@", value)

base_cli/testing.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .paths import use_working_dir
+
+if TYPE_CHECKING:
+    from click.testing import Result
+
+
+# pylint: disable=too-many-arguments
+def invoke(
+    app: Any,
+    args: list[str] | None = None,
+    home: Path | None = None,
+    cwd: Path | str | None = None,
+    env: dict[str, str] | None = None,
+    *,
+    manifest: Mapping[str, Any] | None = None,
+) -> Result:
+    cwd_path = Path(cwd).expanduser().resolve() if cwd is not None else None
+    if manifest is not None:
+        if cwd_path is None:
+            raise ValueError("manifest requires cwd so base_manifest.yaml has a target directory.")
+        _write_manifest_fixture(cwd_path, manifest)
+
+    try:
+        from click.testing import CliRunner
+    except ImportError as exc:
+        raise RuntimeError("Click is required for base_cli.testing. Install it with 'pip install click'.") from exc
+
+    invoke_env = dict(env or {})
+    if home is not None:
+        invoke_env.setdefault("HOME", str(home))
+        invoke_env.setdefault("BASE_CACHE_DIR", str(home / ".cache" / "base"))
+    runner_kwargs = {}
+    if "mix_stderr" in inspect.signature(CliRunner).parameters:
+        runner_kwargs["mix_stderr"] = False
+    runner = CliRunner(**runner_kwargs)
+    with use_working_dir(cwd_path):
+        return runner.invoke(app.click_command, args or [], env=invoke_env)
+
+
+def _write_manifest_fixture(cwd: Path, manifest: Mapping[str, Any]) -> None:
+    try:
+        import yaml
+    except ImportError as exc:
+        raise RuntimeError(
+            "PyYAML is required to write base_cli.testing manifest fixtures. "
+            "Install it with 'pip install PyYAML'."
+        ) from exc
+
+    (cwd / "base_manifest.yaml").write_text(
+        yaml.safe_dump(dict(manifest), sort_keys=False),
+        encoding="utf-8",
+    )