base-cli 0.1.0__py3-none-any.whl

base_cli/command_protocol.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+__all__ = [
+    "CommandProtocolError",
+    "dumps_record",
+    "dumps_records",
+    "loads_records",
+]
+
+
+PROTOCOL_HEADER = "BASE_COMMAND_PROTOCOL_V1"
+MAX_RECORD_COUNT = 1_000_000
+
+
+class CommandProtocolError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class FieldSpec:
+    value_type: str
+    nullable: bool = False
+
+
+STRING = FieldSpec("string")
+NULLABLE_STRING = FieldSpec("string", nullable=True)
+BOOLEAN = FieldSpec("boolean")
+
+PROJECT_REFERENCE_FIELDS = {
+    "project_name": STRING,
+    "project_root": STRING,
+    "manifest_path": STRING,
+}
+PROJECT_ROUTE_FIELDS = {
+    **PROJECT_REFERENCE_FIELDS,
+    "project_venv_dir": STRING,
+    "uses_uv_manager": BOOLEAN,
+    "manifest_command_trust_required": BOOLEAN,
+}
+PROJECT_SETUP_ROUTE_FIELDS = {
+    **PROJECT_ROUTE_FIELDS,
+    "requires_project_python": BOOLEAN,
+}
+
+RECORD_SCHEMAS: dict[str, dict[str, FieldSpec]] = {
+    "project-list-entry": {
+        "project_name": STRING,
+        "project_root": STRING,
+    },
+    "project-reference": PROJECT_REFERENCE_FIELDS,
+    "project-route": PROJECT_ROUTE_FIELDS,
+    "project-setup-route": PROJECT_SETUP_ROUTE_FIELDS,
+    "project-command": {
+        **PROJECT_ROUTE_FIELDS,
+        "command": STRING,
+        "runner": NULLABLE_STRING,
+    },
+    "named-command": {
+        **PROJECT_REFERENCE_FIELDS,
+        "command_name": STRING,
+        "command": STRING,
+        "runner": NULLABLE_STRING,
+    },
+    "build-target": {
+        **PROJECT_ROUTE_FIELDS,
+        "target_name": STRING,
+        "working_dir": STRING,
+        "command": STRING,
+        "description": NULLABLE_STRING,
+        "runner": NULLABLE_STRING,
+    },
+    "demo": {
+        **PROJECT_ROUTE_FIELDS,
+        "demo_script": STRING,
+        "runner": NULLABLE_STRING,
+    },
+    "activation-source": {
+        "source_path": STRING,
+    },
+}
+
+RecordValue = str | bool | None
+Record = Mapping[str, RecordValue]
+
+
+def dumps_record(record_type: str, record: Record) -> str:
+    return dumps_records(record_type, (record,))
+
+
+def dumps_records(record_type: str, records: tuple[Record, ...] | list[Record]) -> str:
+    schema = _schema(record_type)
+    if len(records) > MAX_RECORD_COUNT:
+        raise CommandProtocolError(f"record_count exceeds protocol maximum of {MAX_RECORD_COUNT}")
+    lines = [
+        PROTOCOL_HEADER,
+        f"record_type={record_type}",
+        f"record_count={len(records)}",
+    ]
+    for index, record in enumerate(records):
+        _validate_record(schema, record_type, record)
+        lines.append(f"record={index}")
+        for field_name, spec in schema.items():
+            wire_type, payload = _encode_value(field_name, spec, record[field_name])
+            lines.append(f"field.{field_name}:{wire_type}={payload}")
+        lines.append(f"end_record={index}")
+    lines.append("end_protocol=")
+    return "\n".join(lines)
+
+
+def loads_records(
+    payload: str,
+    expected_record_type: str | None = None,
+) -> tuple[str, tuple[dict[str, RecordValue], ...]]:
+    # The wire framing is LF-delimited. `str.splitlines()` also accepts CR,
+    # vertical tab, form feed, and Unicode separators, which would make the
+    # Python decoder more permissive than the Bash and Zsh readers.
+    # A CLI `print()` adds one terminal LF; accept that conventional text-file
+    # terminator without accepting an extra blank line or other separators.
+    framed_payload = payload.removesuffix("\n")
+    lines = framed_payload.split("\n")
+    cursor = 0
+
+    def take(label: str) -> str:
+        nonlocal cursor
+        if cursor >= len(lines):
+            raise CommandProtocolError(f"missing {label}")
+        line = lines[cursor]
+        cursor += 1
+        return line
+
+    if take("protocol header") != PROTOCOL_HEADER:
+        raise CommandProtocolError(f"unsupported protocol header; expected {PROTOCOL_HEADER}")
+
+    record_type = _metadata_value(take("record_type"), "record_type")
+    schema = _schema(record_type)
+    if expected_record_type is not None and record_type != expected_record_type:
+        raise CommandProtocolError(f"expected record_type '{expected_record_type}', got '{record_type}'")
+
+    record_count_text = _metadata_value(take("record_count"), "record_count")
+    record_count = _parse_record_count(record_count_text)
+
+    records: list[dict[str, RecordValue]] = []
+    for index in range(record_count):
+        if take(f"record {index}") != f"record={index}":
+            raise CommandProtocolError(f"expected record={index}")
+
+        record: dict[str, RecordValue] = {}
+        for _field_index in range(len(schema)):
+            field_name, wire_type, encoded_value = _parse_field_line(take(f"field in record {index}"))
+            if field_name in record:
+                raise CommandProtocolError(f"record {index} duplicates field '{field_name}'")
+            try:
+                spec = schema[field_name]
+            except KeyError as exc:
+                raise CommandProtocolError(
+                    f"record {index} has unknown field '{field_name}' for '{record_type}'"
+                ) from exc
+            record[field_name] = _decode_value(field_name, spec, wire_type, encoded_value)
+
+        missing = sorted(set(schema) - set(record))
+        if missing:
+            raise CommandProtocolError(f"record {index} is missing fields: {', '.join(missing)}")
+        if take(f"end_record {index}") != f"end_record={index}":
+            raise CommandProtocolError(f"expected end_record={index}")
+        records.append(record)
+
+    if take("end_protocol") != "end_protocol=":
+        raise CommandProtocolError("expected end_protocol marker")
+    if cursor != len(lines):
+        raise CommandProtocolError("unexpected data after end_protocol marker")
+    return record_type, tuple(records)
+
+
+def _schema(record_type: str) -> dict[str, FieldSpec]:
+    try:
+        return RECORD_SCHEMAS[record_type]
+    except KeyError as exc:
+        supported = ", ".join(sorted(RECORD_SCHEMAS))
+        raise CommandProtocolError(f"unsupported record_type '{record_type}'; expected one of: {supported}") from exc
+
+
+def _validate_record(schema: Mapping[str, FieldSpec], record_type: str, record: Record) -> None:
+    missing = sorted(set(schema) - set(record))
+    unknown = sorted(set(record) - set(schema))
+    if missing:
+        raise CommandProtocolError(f"record for '{record_type}' is missing fields: {', '.join(missing)}")
+    if unknown:
+        raise CommandProtocolError(f"record for '{record_type}' has unknown fields: {', '.join(unknown)}")
+
+
+def _encode_value(field_name: str, spec: FieldSpec, value: RecordValue) -> tuple[str, str]:
+    if value is None:
+        if not spec.nullable:
+            raise CommandProtocolError(f"field '{field_name}' cannot be null")
+        return "null", ""
+    if spec.value_type == "boolean":
+        if not isinstance(value, bool):
+            raise CommandProtocolError(f"field '{field_name}' must be a boolean")
+        return "boolean", "true" if value else "false"
+    if not isinstance(value, str):
+        raise CommandProtocolError(f"field '{field_name}' must be a string")
+    if "\0" in value:
+        raise CommandProtocolError(f"field '{field_name}' cannot contain NUL")
+    return "string", value.encode("utf-8").hex()
+
+
+def _decode_value(field_name: str, spec: FieldSpec, wire_type: str, payload: str) -> RecordValue:
+    if wire_type == "null":
+        if not spec.nullable:
+            raise CommandProtocolError(f"field '{field_name}' cannot be null")
+        if payload:
+            raise CommandProtocolError(f"null field '{field_name}' must have an empty payload")
+        return None
+    if spec.value_type == "boolean":
+        if wire_type != "boolean" or payload not in ("true", "false"):
+            raise CommandProtocolError(f"field '{field_name}' must use boolean:true or boolean:false")
+        return payload == "true"
+    if wire_type != "string":
+        expected = "string or null" if spec.nullable else "string"
+        raise CommandProtocolError(f"field '{field_name}' must use {expected} encoding")
+    if len(payload) % 2 != 0 or re.fullmatch(r"[0-9a-f]*", payload) is None:
+        raise CommandProtocolError(f"field '{field_name}' has invalid lowercase hexadecimal data")
+    try:
+        value = bytes.fromhex(payload).decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise CommandProtocolError(f"field '{field_name}' has invalid UTF-8 data") from exc
+    if "\0" in value:
+        raise CommandProtocolError(f"field '{field_name}' cannot contain NUL")
+    return value
+
+
+def _metadata_value(line: str, name: str) -> str:
+    prefix = f"{name}="
+    if not line.startswith(prefix):
+        raise CommandProtocolError(f"expected {name} metadata")
+    return line[len(prefix) :]
+
+
+def _parse_record_count(record_count_text: str) -> int:
+    if re.fullmatch(r"0|[1-9][0-9]*", record_count_text) is None:
+        raise CommandProtocolError("record_count must be a canonical non-negative integer")
+    if len(record_count_text) > len(str(MAX_RECORD_COUNT)):
+        raise CommandProtocolError(f"record_count exceeds protocol maximum of {MAX_RECORD_COUNT}")
+    record_count = int(record_count_text)
+    if record_count > MAX_RECORD_COUNT:
+        raise CommandProtocolError(f"record_count exceeds protocol maximum of {MAX_RECORD_COUNT}")
+    return record_count
+
+
+def _parse_field_line(line: str) -> tuple[str, str, str]:
+    key, separator, payload = line.partition("=")
+    if not separator or not key.startswith("field."):
+        raise CommandProtocolError("expected field.<name>:<type>=<payload>")
+    descriptor = key.removeprefix("field.")
+    field_name, separator, wire_type = descriptor.partition(":")
+    if not separator or not field_name or not wire_type:
+        raise CommandProtocolError("expected field.<name>:<type>=<payload>")
+    return field_name, wire_type, payload

base_cli/config.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import re
+from typing import Any
+
+from .ide_schema import SUPPORTED_IDES
+from .ide_schema import parse_ide_extensions
+from .ide_schema import parse_ide_settings
+from .paths import base_state_root
+
+
+__all__ = [
+    "UserConfig",
+    "UserGithubConfig",
+    "UserIdeConfig",
+    "UserIdePreference",
+    "UserWorkspaceConfig",
+]
+
+
+@dataclass(frozen=True)
+class UserIdePreference:
+    enabled: bool | None
+    install: bool | None
+    extra_extensions: tuple[str, ...]
+    settings: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class UserIdeConfig:
+    enabled: bool | None
+    preferences: dict[str, UserIdePreference]
+
+
+@dataclass(frozen=True)
+class UserWorkspaceConfig:
+    root: Path | None
+    manifest: Path | None = None
+    manifest_source: str | None = None
+
+
+@dataclass(frozen=True)
+class UserGithubConfig:
+    default_owner: str | None
+    clone_protocol: str | None
+
+
+@dataclass(frozen=True)
+class UserConfig:
+    raw: dict[str, Any]
+    ide: UserIdeConfig
+    workspace: UserWorkspaceConfig = UserWorkspaceConfig(root=None)
+    github: UserGithubConfig = UserGithubConfig(default_owner=None, clone_protocol=None)
+
+
+def user_config_path(home: Path | None = None) -> Path:
+    return base_state_root(home) / "config.yaml"
+
+
+def load_yaml_file(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+
+    try:
+        import yaml
+    except ImportError as exc:
+        raise RuntimeError("PyYAML is required to load base_cli configuration.") from exc
+
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ValueError(f"Config file '{path}' contains invalid YAML: {exc}") from exc
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(f"Config file '{path}' must contain a YAML mapping.")
+    return data
+
+
+def load_user_config(home: Path | None = None) -> dict[str, Any]:
+    return load_yaml_file(user_config_path(home))
+
+
+def read_user_config(home: Path | None = None) -> UserConfig:
+    raw = load_user_config(home)
+    path = user_config_path(home)
+    return UserConfig(
+        raw=raw,
+        workspace=_read_user_workspace_config(path, raw.get("workspace")),
+        github=_read_user_github_config(path, raw.get("github")),
+        ide=_read_user_ide_config(path, raw.get("ide")),
+    )
+
+
+def _read_user_workspace_config(path: Path, workspace_data: Any) -> UserWorkspaceConfig:
+    if workspace_data is None:
+        return UserWorkspaceConfig(root=None)
+    if not isinstance(workspace_data, dict):
+        raise ValueError(f"{path}: workspace must be a mapping when provided.")
+
+    allowed_keys = {"root", "manifest", "manifest_source"}
+    unknown_keys = sorted(set(workspace_data) - allowed_keys)
+    if unknown_keys:
+        raise ValueError(f"{path}: workspace has unsupported keys: {', '.join(unknown_keys)}.")
+
+    return UserWorkspaceConfig(
+        root=_optional_path(path, "workspace.root", workspace_data.get("root")),
+        manifest=_optional_path(path, "workspace.manifest", workspace_data.get("manifest")),
+        manifest_source=_optional_non_empty_string(
+            path,
+            "workspace.manifest_source",
+            workspace_data.get("manifest_source"),
+        ),
+    )
+
+
+def _read_user_github_config(path: Path, github_data: Any) -> UserGithubConfig:
+    if github_data is None:
+        return UserGithubConfig(default_owner=None, clone_protocol=None)
+    if not isinstance(github_data, dict):
+        raise ValueError(f"{path}: github must be a mapping when provided.")
+
+    allowed_keys = {"default_owner", "clone_protocol"}
+    unknown_keys = sorted(set(github_data) - allowed_keys)
+    if unknown_keys:
+        raise ValueError(f"{path}: github has unsupported keys: {', '.join(unknown_keys)}.")
+
+    return UserGithubConfig(
+        default_owner=_optional_github_owner(path, github_data.get("default_owner")),
+        clone_protocol=_optional_github_clone_protocol(path, github_data.get("clone_protocol")),
+    )
+
+
+def _optional_github_owner(path: Path, value: Any) -> str | None:
+    owner = _optional_non_empty_string(path, "github.default_owner", value)
+    if owner is None:
+        return None
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9-]*", owner):
+        raise ValueError(
+            f"{path}: github.default_owner must start with a letter or digit and contain only "
+            "letters, digits, and dash."
+        )
+    return owner
+
+
+def _optional_github_clone_protocol(path: Path, value: Any) -> str | None:
+    protocol = _optional_non_empty_string(path, "github.clone_protocol", value)
+    if protocol is None:
+        return None
+    if protocol not in {"ssh", "https"}:
+        raise ValueError(f"{path}: github.clone_protocol must be 'ssh' or 'https'.")
+    return protocol
+
+
+def _optional_path(path: Path, key: str, value: Any) -> Path | None:
+    if value is None:
+        return None
+    candidate = _optional_non_empty_string(path, key, value)
+    if candidate is None:
+        return None
+
+    candidate_path = Path(candidate).expanduser()
+    if not candidate_path.is_absolute():
+        raise ValueError(f"{path}: {key} must be an absolute path or start with '~'.")
+    return candidate_path.resolve(strict=False)
+
+
+def _optional_non_empty_string(path: Path, key: str, value: Any) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{path}: {key} must be a non-empty string when provided.")
+    return value.strip()
+
+
+def _read_user_ide_config(path: Path, ide_data: Any) -> UserIdeConfig:
+    if ide_data is None:
+        return UserIdeConfig(enabled=None, preferences={})
+    if not isinstance(ide_data, dict):
+        raise ValueError(f"{path}: ide must be a mapping when provided.")
+
+    allowed_keys = SUPPORTED_IDES | {"enabled"}
+    unknown_keys = sorted(set(ide_data) - allowed_keys)
+    if unknown_keys:
+        raise ValueError(f"{path}: unsupported ide keys: {', '.join(unknown_keys)}.")
+
+    enabled = _optional_bool(path, "ide.enabled", ide_data.get("enabled"))
+    preferences = {
+        ide_name: _read_user_ide_preference(path, ide_name, ide_data.get(ide_name))
+        for ide_name in sorted(SUPPORTED_IDES)
+        if ide_name in ide_data
+    }
+    return UserIdeConfig(enabled=enabled, preferences=preferences)
+
+
+def _read_user_ide_preference(path: Path, ide_name: str, preference_data: Any) -> UserIdePreference:
+    if preference_data is None:
+        preference_data = {}
+    if not isinstance(preference_data, dict):
+        raise ValueError(f"{path}: ide.{ide_name} must be a mapping when provided.")
+
+    allowed_keys = {"enabled", "install", "extra_extensions", "settings"}
+    unknown_keys = sorted(set(preference_data) - allowed_keys)
+    if unknown_keys:
+        raise ValueError(f"{path}: ide.{ide_name} has unsupported keys: {', '.join(unknown_keys)}.")
+
+    enabled = _optional_bool(path, f"ide.{ide_name}.enabled", preference_data.get("enabled"))
+    install = _optional_bool(path, f"ide.{ide_name}.install", preference_data.get("install"))
+    extra_extensions = _read_extra_extensions(path, ide_name, preference_data.get("extra_extensions", []))
+    settings = _read_user_ide_settings(path, ide_name, preference_data.get("settings", {}))
+    return UserIdePreference(
+        enabled=enabled,
+        install=install,
+        extra_extensions=extra_extensions,
+        settings=settings,
+    )
+
+
+def _optional_bool(path: Path, key: str, value: Any) -> bool | None:
+    if value is None:
+        return None
+    if not isinstance(value, bool):
+        raise ValueError(f"{path}: {key} must be a boolean when provided.")
+    return value
+
+
+def _read_extra_extensions(path: Path, ide_name: str, extensions_data: Any) -> tuple[str, ...]:
+    return parse_ide_extensions(f"{path}: ide.{ide_name}.extra_extensions", extensions_data)
+
+
+def _read_user_ide_settings(path: Path, ide_name: str, settings_data: Any) -> dict[str, Any]:
+    return parse_ide_settings(f"{path}: ide.{ide_name}.settings", settings_data)
+
+
+def merge_dicts(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = merge_dicts(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def load_config(
+    project_root: Path | None,
+    explicit_config: Path | None,
+    home: Path | None = None,
+) -> dict[str, Any]:
+    root = home or Path.home()
+    config: dict[str, Any] = {}
+    config = merge_dicts(config, load_user_config(root))
+    if project_root is not None:
+        config = merge_dicts(config, load_yaml_file(project_root / ".base" / "config.yaml"))
+    if explicit_config is not None:
+        config = merge_dicts(config, load_yaml_file(explicit_config))
+
+    env_config: dict[str, Any] = {}
+    if "BASE_CLI_ENVIRONMENT" in os.environ:
+        env_config["environment"] = os.environ["BASE_CLI_ENVIRONMENT"]
+    if "BASE_CLI_LOG_LEVEL" in os.environ:
+        env_config["log_level"] = os.environ["BASE_CLI_LOG_LEVEL"]
+    elif os.environ.get("LOG_DEBUG", "").lower() in ("1", "true"):
+        env_config["log_level"] = "debug"
+    if "BASE_CLI_KEEP_TEMP" in os.environ:
+        env_config["keep_temp"] = os.environ["BASE_CLI_KEEP_TEMP"].lower() == "true"
+    return merge_dicts(config, env_config)

base_cli/context.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import contextvars
+import logging
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from .config import UserConfig, UserIdeConfig
+
+
+_current_context: contextvars.ContextVar[Context | None] = contextvars.ContextVar(
+    "base_cli_current_context",
+    default=None,
+)
+
+
+def _default_user_config() -> UserConfig:
+    return UserConfig(raw={}, ide=UserIdeConfig(enabled=None, preferences={}))
+
+
+@dataclass
+class Context:
+    """Runtime state and cleanup hooks available to an active Base CLI command."""
+
+    cli_name: str
+    run_id: str
+    state_dir: Path
+    log_dir: Path
+    cache_dir: Path
+    temp_dir: Path
+    log_file: Path | None
+    config: dict[str, Any]
+    environment: str
+    debug: bool
+    keep_temp: bool
+    log: logging.Logger
+    dry_run: bool = False
+    base_home: Path | None = None
+    project_root: Path | None = None
+    manifest_path: Path | None = None
+    project_name: str | None = None
+    history_scope: str = "primary"
+    history_parent_run_id: str | None = None
+    user_config: UserConfig = field(default_factory=_default_user_config)
+    cleanup_hooks: list[Callable[[], None]] = field(default_factory=list)
+    workspace_root: Path | None = None
+    quiet: bool = False
+    runtime_owner: str = "base"
+    owner_root: Path | None = None
+    run_root: Path | None = None
+
+    def on_cleanup(self, hook: Callable[[], None]) -> None:
+        self.cleanup_hooks.append(hook)
+
+    def bind_project(self, project_name: str | None, project_root: Path, manifest_path: Path | None = None) -> None:
+        """Bind the selected project to this invocation's history context."""
+        self.project_name = project_name
+        self.project_root = project_root.resolve()
+        self.manifest_path = manifest_path.resolve() if manifest_path is not None else None
+
+    def cleanup(self) -> None:
+        for hook in self.cleanup_hooks:
+            try:
+                hook()
+            except Exception as exc:  # pylint: disable=broad-exception-caught
+                self.log.warning("Cleanup hook failed: %s", exc)
+        if not self.keep_temp and self.temp_dir.exists():
+            try:
+                shutil.rmtree(self.temp_dir)
+                for parent in (self.temp_dir.parent, self.temp_dir.parent.parent):
+                    try:
+                        parent.rmdir()
+                    except OSError:
+                        break
+            except OSError as exc:
+                self.log.warning("Temp directory cleanup failed for '%s': %s", self.temp_dir, exc)
+        for handler in list(self.log.handlers):
+            try:
+                handler.flush()
+            except Exception as exc:  # pylint: disable=broad-exception-caught
+                self.log.warning("Log handler flush failed: %s", exc)
+            try:
+                handler.close()
+            except Exception as exc:  # pylint: disable=broad-exception-caught
+                self.log.warning("Log handler close failed: %s", exc)
+            self.log.removeHandler(handler)
+
+
+def set_current_context(context: Context | None) -> contextvars.Token[Context | None]:
+    return _current_context.set(context)
+
+
+def reset_current_context(token: contextvars.Token[Context | None]) -> None:
+    _current_context.reset(token)
+
+
+def get_current_context() -> Context:
+    context = _current_context.get()
+    if context is None:
+        raise RuntimeError("base_cli context is not active. Run inside a base_cli.App command.")
+    return context

base_cli/exit_codes.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class ExitCode:
+    """Base-standard command exit code constants."""
+
+    SUCCESS = 0
+    FAILURE = 1
+    USAGE_ERROR = 2