hoja-cli 0.21.4__py3-none-any.whl

hoja/config.py

@@ -0,0 +1,362 @@
+"""Config loading and validation.
+
+Lookup order:
+  1. $HOJA_CONFIG env var (absolute path)
+  2. Existing or new $XDG_CONFIG_HOME/hoja/config.toml
+
+Token resolution order (per account):
+  1. --token CLI flag (passed in)
+  2. $<ACCOUNT_TOKEN_ENV> environment variable (default: HOJA_TOKEN,
+     with deprecated LINEAR_TOKEN still read as a fallback)
+  3. config.toml [accounts.<name>].token (discouraged)
+
+Account resolution order:
+  1. --account CLI flag
+  2. Workspace-mapped account (git repo root → config.workspaces)
+  3. Global default account (config.defaults.default_account)
+  4. First available account (fallback)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+try:
+    import tomli_w
+except ImportError:  # pragma: no cover
+    tomli_w = None  # type: ignore[assignment]
+
+import contextlib
+
+from hoja.errors import AuthError, UsageError
+
+# Deprecated environment-variable aliases kept for wire compatibility.
+# The HOJA_* name is canonical: it is read first, and the LINEAR_* name is
+# consulted only when the canonical variable is unset. Convenience aliases are
+# NOT inherited by accounts that declare their own ``token_env``.
+LEGACY_ENV_ALIASES: dict[str, str] = {
+    "HOJA_TOKEN": "LINEAR_TOKEN",
+    "HOJA_API_URL": "LINEAR_API_URL",
+}
+
+
+def env_with_legacy(name: str) -> str | None:
+    """Read ``$name``, falling back to its deprecated alias when it has one."""
+    if value := os.environ.get(name):
+        return value
+    alias = LEGACY_ENV_ALIASES.get(name)
+    if alias and (value := os.environ.get(alias)):
+        return value
+    return None
+
+
+class AccountConfig(BaseModel):
+    """A named Hoja account."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    token: str | None = None
+    # Environment variable holding this account's token. HOJA_TOKEN is read
+    # first and the deprecated LINEAR_TOKEN is used only if HOJA_TOKEN is unset.
+    token_env: str = "HOJA_TOKEN"
+    org_name: str | None = None
+    # GraphQL endpoint override. Point this at a local hoja-serve backend
+    # (e.g. "http://127.0.0.1:8787/graphql") to run fully offline. When unset,
+    # hoja talks to the configured Linear-compatible API. $HOJA_API_URL
+    # (or its deprecated alias $LINEAR_API_URL) overrides this too.
+    base_url: str | None = None
+    # Team keys this account owns (e.g. ["SWA", "ENG"]). Used for intelligent
+    # account auto-selection: a command targeting team SWA (via --team SWA or
+    # an identifier like SWA-20) picks the account that lists "SWA" here.
+    teams: list[str] = Field(default_factory=list)
+
+
+class DefaultsConfig(BaseModel):
+    """Default values applied to commands."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    team: str | None = None
+    output: str = "human"
+    editor: str | None = None
+    default_account: str | None = None
+
+
+class DisplayConfig(BaseModel):
+    """Display preferences."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    color: bool = True
+    table_max_width: int = 120
+    truncate_descriptions: int = 80
+
+
+class Config(BaseModel):
+    """Top-level Hoja configuration."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Multi-account support (replaces single [auth] section)
+    accounts: dict[str, AccountConfig] = Field(default_factory=dict)
+    # Legacy [auth] section — present for loading old configs, migrated to accounts.default
+    auth: dict[str, Any] | None = None
+
+    defaults: DefaultsConfig = Field(default_factory=DefaultsConfig)
+    display: DisplayConfig = Field(default_factory=DisplayConfig)
+    aliases: dict[str, str] = Field(default_factory=dict)
+    views: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    # Per-workspace account mappings (absolute repo path → account name)
+    workspaces: dict[str, str] = Field(default_factory=dict)
+
+
+def config_path() -> Path:
+    """Resolve config file location."""
+    if env_path := os.environ.get("HOJA_CONFIG"):
+        return Path(env_path).expanduser().resolve()
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
+    canonical = base / "hoja" / "config.toml"
+    if canonical.exists():
+        return canonical
+    return canonical
+
+
+def _migrate_legacy_auth(data: dict[str, Any]) -> dict[str, Any]:
+    """Migrate old [auth] section to accounts.default."""
+    auth = data.pop("auth", None)
+    if auth and isinstance(auth, dict):
+        accounts = data.setdefault("accounts", {})
+        # Only migrate if accounts.default doesn't already exist
+        if "default" not in accounts:
+            accounts["default"] = {}
+        default = accounts["default"]
+        if "token" in auth and "token" not in default:
+            default["token"] = auth["token"]
+        if "token_env" in auth and "token_env" not in default:
+            default["token_env"] = auth["token_env"]
+    return data
+
+
+def load_config(path: Path | None = None) -> Config:
+    """Load and validate config.toml. Returns defaults if file missing."""
+    p = path or config_path()
+    if not p.exists():
+        return Config()
+    try:
+        with open(p, "rb") as f:
+            data = tomllib.load(f)
+    except tomllib.TOMLDecodeError as e:
+        raise UsageError(
+            f"Invalid TOML in config file: {e}",
+            hint=f"Edit {p} to fix syntax",
+        ) from e
+
+    # Migrate legacy [auth] section if present
+    data = _migrate_legacy_auth(data)
+
+    try:
+        return Config(**data)
+    except Exception as e:
+        raise UsageError(
+            f"Invalid config: {e}",
+            hint="See docs/DESIGN.md for the config schema",
+        ) from e
+
+
+def save_config(config: Config, path: Path | None = None) -> None:
+    """Save config to disk as TOML."""
+    if tomli_w is None:
+        raise UsageError(
+            "Cannot write config: tomli-w not installed",
+            hint="pip install tomli-w",
+        )
+    p = path or config_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    data = _config_to_dict(config)
+    with open(p, "wb") as f:
+        tomli_w.dump(data, f)
+    with contextlib.suppress(OSError):
+        os.chmod(p, 0o600)
+
+
+def _config_to_dict(config: Config) -> dict[str, Any]:
+    """Serialize Config to a plain dict for TOML writing."""
+    data: dict[str, Any] = {}
+    if config.accounts:
+        data["accounts"] = {
+            name: acc.model_dump(exclude_none=True, exclude_defaults=True)
+            for name, acc in config.accounts.items()
+        }
+    defaults_dict = config.defaults.model_dump(exclude_defaults=True)
+    if defaults_dict:
+        data["defaults"] = defaults_dict
+    display_dict = config.display.model_dump(exclude_defaults=True)
+    if display_dict:
+        data["display"] = display_dict
+    if config.aliases:
+        data["aliases"] = config.aliases
+    if config.views:
+        data["views"] = config.views
+    if config.workspaces:
+        data["workspaces"] = config.workspaces
+    return data
+
+
+def _find_git_root(start: Path | None = None) -> Path | None:
+    """Walk up from start (or cwd) looking for a .git directory."""
+    start = start or Path.cwd()
+    path = start.resolve()
+    for parent in [path, *path.parents]:
+        if (parent / ".git").is_dir():
+            return parent
+    return None
+
+
+def resolve_workspace(path: Path | None = None) -> Path | None:
+    """Resolve the current workspace directory (git repo root or None)."""
+    return _find_git_root(path)
+
+
+def team_key_from_hint(hint: str | None) -> str | None:
+    """Extract an uppercase team key from a --team value or an issue identifier.
+
+    Accepts a bare key ("SWA") or an identifier ("SWA-20") and returns "SWA".
+    Returns None for UUIDs, empty values, or anything without a key prefix.
+    """
+    if not hint:
+        return None
+    h = hint.strip()
+    # UUIDs (36 chars, 4 dashes) are not team keys.
+    if len(h) == 36 and h.count("-") == 4:
+        return None
+    # Identifier form KEY-123 → KEY
+    prefix = h.split("-", 1)[0]
+    if prefix.isalpha():
+        return prefix.upper()
+    return None
+
+
+def resolve_account(
+    cli_account: str | None,
+    config: Config,
+    workspace_path: Path | None = None,
+    team_key: str | None = None,
+) -> tuple[str, AccountConfig]:
+    """Resolve which account to use.
+
+    Order:
+      1. --account CLI flag
+      2. Team-key-owning account (account.teams contains team_key)
+      3. Workspace-mapped account
+      4. Global default account
+      5. First available account (fallback)
+      6. Not found → synthetic default (lets resolve_token check $HOJA_TOKEN)
+
+    Returns (account_name, account_config).
+    """
+    # 1. CLI flag
+    if cli_account:
+        if cli_account not in config.accounts:
+            raise AuthError(
+                f"Account '{cli_account}' not found",
+                hint="Run 'hoja auth accounts' to see available accounts.",
+            )
+        return cli_account, config.accounts[cli_account]
+
+    # 2. Team-key ownership — pick the account that declares this team key.
+    key = team_key_from_hint(team_key)
+    if key:
+        for name, acc in config.accounts.items():
+            if any(t.strip().upper() == key for t in acc.teams):
+                return name, acc
+
+    # 3. Workspace-mapped
+    workspace = resolve_workspace(workspace_path)
+    if workspace:
+        ws_key = str(workspace)
+        mapped = config.workspaces.get(ws_key)
+        if mapped and mapped in config.accounts:
+            return mapped, config.accounts[mapped]
+
+    # 4. Global default
+    if (
+        config.defaults.default_account
+        and config.defaults.default_account in config.accounts
+    ):
+        return (
+            config.defaults.default_account,
+            config.accounts[config.defaults.default_account],
+        )
+
+    # 5. Fallback to any configured account
+    if config.accounts:
+        first_name = next(iter(config.accounts))
+        return first_name, config.accounts[first_name]
+
+    # 6. Env-only fallback: no accounts configured but $HOJA_TOKEN (or the
+    # deprecated $LINEAR_TOKEN) may exist. Return a synthetic default account so
+    # resolve_token can check the env var.
+    return "default", AccountConfig(token_env="HOJA_TOKEN")
+
+
+def resolve_token(
+    cli_token: str | None,
+    account: AccountConfig,
+) -> str:
+    """Resolve the API token using precedence rules.
+
+    Order: --token > $<ACCOUNT_TOKEN_ENV> > account.token.
+    The default token env var is HOJA_TOKEN; LINEAR_TOKEN is still accepted as
+    a deprecated alias when HOJA_TOKEN is unset.
+    """
+    if cli_token:
+        return cli_token
+    env_var = account.token_env or "HOJA_TOKEN"
+    if env_token := env_with_legacy(env_var):
+        return env_token
+    if account.token:
+        return account.token
+    alias = LEGACY_ENV_ALIASES.get(env_var)
+    hint_vars = f"${env_var} (or ${alias})" if alias else f"${env_var}"
+    raise AuthError(
+        "No Hoja API token found",
+        hint=(
+            f"Set {hint_vars}, pass --token, or configure token in "
+            f"{config_path()}"
+        ),
+    )
+
+
+def resolve_base_url(
+    cli_base_url: str | None,
+    account: AccountConfig,
+) -> str | None:
+    """Resolve the GraphQL endpoint override.
+
+    Order: --api-url flag > $HOJA_API_URL env (deprecated alias
+    $LINEAR_API_URL) > account.base_url > None.
+    Returning None means "use the client's default endpoint".
+    """
+    if cli_base_url:
+        return cli_base_url
+    if env_url := env_with_legacy("HOJA_API_URL"):
+        return env_url
+    return account.base_url
+
+
+def redact_token(token: str) -> str:
+    """Show only the last 4 chars of a token for logging."""
+    if len(token) <= 8:
+        return "***"
+    return f"{token[:8]}…{token[-4:]}"

hoja/errors.py

@@ -0,0 +1,107 @@
+"""Error hierarchy and exit codes for hoja.
+
+Exit codes are stable across versions — scripts can rely on them.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Any
+
+
+class ExitCode(IntEnum):
+    """Stable CLI exit codes. Do not reorder."""
+
+    SUCCESS = 0
+    GENERIC_ERROR = 1
+    USAGE_ERROR = 2
+    AUTH_ERROR = 3
+    NOT_FOUND = 4
+    VALIDATION_ERROR = 5
+    API_ERROR = 6
+    NETWORK_ERROR = 7
+    RATE_LIMITED = 8
+
+
+class HojaError(Exception):
+    """Base class for all hoja errors."""
+
+    exit_code: ExitCode = ExitCode.GENERIC_ERROR
+
+    def __init__(self, message: str, *, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize for `-o json` output on error."""
+        return {
+            "error": {
+                "type": self.__class__.__name__,
+                "code": int(self.exit_code),
+                "message": self.message,
+                "hint": self.hint,
+            }
+        }
+
+
+class AuthError(HojaError):
+    """Missing or invalid Linear API token."""
+
+    exit_code = ExitCode.AUTH_ERROR
+
+
+class NotFoundError(HojaError):
+    """Requested entity does not exist."""
+
+    exit_code = ExitCode.NOT_FOUND
+
+
+class ValidationError(HojaError):
+    """Response did not match expected Pydantic model."""
+
+    exit_code = ExitCode.VALIDATION_ERROR
+
+
+class APIError(HojaError):
+    """The GraphQL API returned an error."""
+
+    exit_code = ExitCode.API_ERROR
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        errors: list[dict[str, Any]] | None = None,
+        hint: str | None = None,
+    ) -> None:
+        super().__init__(message, hint=hint)
+        self.errors = errors or []
+
+    def to_dict(self) -> dict[str, Any]:
+        d = super().to_dict()
+        d["error"]["linear_errors"] = self.errors
+        return d
+
+
+class NetworkError(HojaError):
+    """HTTP transport error: timeout, DNS, TLS."""
+
+    exit_code = ExitCode.NETWORK_ERROR
+
+
+class RateLimitError(HojaError):
+    """The API rate limit was exceeded."""
+
+    exit_code = ExitCode.RATE_LIMITED
+
+    def __init__(self, message: str, *, retry_after: int | None = None) -> None:
+        hint = f"Retry after {retry_after} seconds" if retry_after else None
+        super().__init__(message, hint=hint)
+        self.retry_after = retry_after
+
+
+class UsageError(HojaError):
+    """User supplied invalid arguments."""
+
+    exit_code = ExitCode.USAGE_ERROR

hoja/filters.py

@@ -0,0 +1,150 @@
+"""Filter DSL → Linear's IssueFilter input.
+
+Maps friendly CLI flags (--team ENG, --state "In Progress") onto Linear's
+GraphQL filter input shape.
+
+References:
+- https://linear.app/developers/filtering
+- IssueFilter type in schema/linear-schema.json
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_issue_filter(
+    *,
+    team: str | None = None,
+    state: str | list[str] | None = None,
+    not_state: str | list[str] | None = None,
+    state_type: str | list[str] | None = None,
+    not_state_type: str | list[str] | None = None,
+    assignee: str | None = None,
+    creator: str | None = None,
+    project: str | None = None,
+    cycle: str | None = None,
+    label: str | list[str] | None = None,
+    priority: int | None = None,
+    contains: str | None = None,
+    updated_after: str | None = None,
+    updated_before: str | None = None,
+    due_before: str | None = None,
+    due_after: str | None = None,
+    viewer_id: str | None = None,
+) -> dict[str, Any]:
+    """Build an IssueFilter dict from CLI flags.
+
+    `viewer_id` is required if any field resolves to "me".
+    """
+    f: dict[str, Any] = {}
+
+    if team:
+        # Accept either team key (ENG) or team UUID
+        if _looks_like_uuid(team):
+            f["team"] = {"id": {"eq": team}}
+        else:
+            f["team"] = {"key": {"eq": team.upper()}}
+
+    if state is not None:
+        f["state"] = _str_or_list_filter("name", state)
+    if not_state is not None:
+        f.setdefault("state", {}).update(_str_or_list_negate("name", not_state))
+
+    if state_type is not None:
+        f["state"] = {**f.get("state", {}), **_str_or_list_filter("type", state_type)}
+    if not_state_type is not None:
+        f["state"] = {**f.get("state", {}), **_str_or_list_negate("type", not_state_type)}
+
+    if assignee:
+        f["assignee"] = _user_subfilter(assignee, viewer_id)
+
+    if creator:
+        f["creator"] = _user_subfilter(creator, viewer_id)
+
+    if project:
+        if _looks_like_uuid(project):
+            f["project"] = {"id": {"eq": project}}
+        else:
+            f["project"] = {"name": {"containsIgnoreCase": project}}
+
+    if cycle:
+        if cycle.lower() == "current":
+            # Linear supports cycle: { isActive: { eq: true } } — but only via Team scope
+            # For simplicity expose via cycle filter using number from the resolved cycle id
+            f["cycle"] = {"isActive": {"eq": True}}
+        elif cycle.lower() == "next":
+            f["cycle"] = {"isNext": {"eq": True}}
+        elif _looks_like_uuid(cycle):
+            f["cycle"] = {"id": {"eq": cycle}}
+        else:
+            f["cycle"] = {"name": {"containsIgnoreCase": cycle}}
+
+    if label is not None:
+        f["labels"] = {"name": _str_or_list_op(label)}
+
+    if priority is not None:
+        f["priority"] = {"eq": priority}
+
+    if contains:
+        # Linear's free-text on issue is title/description — use `or`
+        f["or"] = [
+            {"title": {"containsIgnoreCase": contains}},
+            {"description": {"containsIgnoreCase": contains}},
+        ]
+
+    if updated_after:
+        f["updatedAt"] = {**f.get("updatedAt", {}), "gt": updated_after}
+    if updated_before:
+        f["updatedAt"] = {**f.get("updatedAt", {}), "lt": updated_before}
+
+    if due_after:
+        f["dueDate"] = {**f.get("dueDate", {}), "gt": due_after}
+    if due_before:
+        f["dueDate"] = {**f.get("dueDate", {}), "lt": due_before}
+
+    return f
+
+
+def _looks_like_uuid(value: str) -> bool:
+    """Cheap UUID detector — Linear IDs are 36-char UUIDs with hyphens."""
+    return len(value) == 36 and value.count("-") == 4
+
+
+def _str_or_list_op(value: str | list[str]) -> dict[str, Any]:
+    """Produce eq/in clause depending on type."""
+    if isinstance(value, str):
+        if "," in value:
+            return {"in": [v.strip() for v in value.split(",")]}
+        return {"eq": value}
+    return {"in": value}
+
+
+def _str_or_list_filter(field: str, value: str | list[str]) -> dict[str, Any]:
+    return {field: _str_or_list_op(value)}
+
+
+def _str_or_list_negate(field: str, value: str | list[str]) -> dict[str, Any]:
+    op = _str_or_list_op(value)
+    if "eq" in op:
+        return {field: {"neq": op["eq"]}}
+    if "in" in op:
+        return {field: {"nin": op["in"]}}
+    return {}
+
+
+def _user_subfilter(value: str, viewer_id: str | None) -> dict[str, Any]:
+    """Resolve 'me', a UUID, or an email to a Linear user filter."""
+    v = value.strip()
+    if v.lower() == "me":
+        if not viewer_id:
+            raise ValueError(
+                "Used 'me' as assignee/creator but viewer hasn't been resolved"
+            )
+        return {"id": {"eq": viewer_id}}
+    if _looks_like_uuid(v):
+        return {"id": {"eq": v}}
+    if "@" in v:
+        return {"email": {"eq": v}}
+    # Fall back: display name contains
+    return {"displayName": {"containsIgnoreCase": v}}

hoja/graphql/__init__.py

@@ -0,0 +1,5 @@
+"""GraphQL query/mutation strings and fragments.
+
+We keep raw GraphQL here rather than codegen so dependencies stay minimal
+and queries stay readable/auditable.
+"""