hoja-cli 0.21.4__py3-none-any.whl

hoja/commands/memory.py

@@ -0,0 +1,240 @@
+"""`hoja memory` commands — project-scoped memory board for agents.
+
+The memory board lives at `.hoja/memory.yaml` (project root). Agents read it
+before starting work (`memory remind`) and contribute learnings (`memory add`).
+Stale community entries auto-heal after 30 days.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from typing import Any
+
+import typer
+
+from hoja.cli_state import get_state
+from hoja.errors import NotFoundError
+from hoja.memory_board import (
+    MemoryBoard,
+    MemoryEntry,
+    heal,
+    load_memory,
+    remind,
+    save_memory,
+)
+from hoja.models.enums import OutputFormat
+
+memory_app = typer.Typer(help="Project memory board for hoja agents")
+
+
+@memory_app.callback(invoke_without_command=True)
+def memory(ctx: typer.Context) -> None:
+    """Memory board — read before work, write after learning."""
+    if ctx.invoked_subcommand is not None:
+        return
+    # Default action: remind
+    _run_remind()
+
+
+@memory_app.command("remind")
+def memory_remind() -> None:
+    """Print the memory board digest (what agents see before starting work)."""
+    _run_remind()
+
+
+def _run_remind() -> None:
+    state = get_state()
+    board = load_memory()
+    digest = remind(board)
+    if state.output == OutputFormat.JSON:
+        data = {
+            "forced": [_entry_dict(e) for e in board.forced],
+            "community": [_entry_dict(e) for e in board.community if not _is_stale(e)],
+        }
+        print(_json.dumps(data, indent=2))
+        return
+    typer.echo(digest)
+
+
+@memory_app.command("list")
+def memory_list() -> None:
+    """List all memory entries with metadata."""
+    state = get_state()
+    board = load_memory()
+    if state.output == OutputFormat.JSON:
+        data = {
+            "forced": [_entry_dict(e) for e in board.forced],
+            "community": [_entry_dict(e) for e in board.community],
+        }
+        print(_json.dumps(data, indent=2))
+        return
+
+    typer.echo("Memory board entries:")
+    typer.echo("")
+    if board.forced:
+        typer.echo("Forced rules:")
+        for e in sorted(board.forced, key=lambda x: x.priority):
+            stale = " [stale]" if _is_stale(e) else ""
+            typer.echo(f"  [{e.priority}] {e.id}{stale}")
+            typer.echo(f"      {e.title}")
+    if board.community:
+        typer.echo("")
+        typer.echo("Community entries:")
+        for e in sorted(board.community, key=lambda x: x.priority):
+            stale = " [stale]" if _is_stale(e) else ""
+            typer.echo(f"  [{e.priority}] {e.id}{stale}")
+            typer.echo(f"      {e.title}")
+            typer.echo(f"      (added {e.created_at[:10]} by {e.created_by})")
+    else:
+        typer.echo("No community entries yet.")
+
+
+@memory_app.command("add")
+def memory_add(
+    title: str = typer.Option(..., "--title", "-t", help="Short title for the memory"),
+    body: str = typer.Option(..., "--body", "-b", help="Body text — what you learned"),
+    priority: int = typer.Option(5, "--priority", "-p", help="Priority 1-10 (1 = most important)"),
+    auto_heal: bool = typer.Option(True, "--auto-heal/--no-auto-heal", help="Auto-remove after heal_after_days"),
+    heal_after_days: int = typer.Option(30, "--heal-after-days", help="Days before auto-removal"),
+) -> None:
+    """Add a community memory entry."""
+    board = load_memory()
+    entry_id = _slugify(title)
+    # Handle duplicates by appending timestamp
+    existing_ids = {e.id for e in board.forced + board.community}
+    if entry_id in existing_ids:
+        entry_id = f"{entry_id}-{__import__('time').time():.0f}"
+
+    entry = MemoryEntry(
+        id=entry_id,
+        priority=priority,
+        title=title,
+        body=body,
+        auto_heal=auto_heal,
+        heal_after_days=heal_after_days,
+    )
+    board.community.append(entry)
+    save_memory(board)
+    typer.echo(f"Added memory '{entry_id}'")
+
+
+@memory_app.command("update")
+def memory_update(
+    entry_id: str = typer.Argument(..., help="Entry ID to update"),
+    body: str | None = typer.Option(None, "--body", "-b", help="New body text"),
+    title: str | None = typer.Option(None, "--title", "-t", help="New title"),
+    priority: int | None = typer.Option(None, "--priority", "-p", help="New priority"),
+) -> None:
+    """Update an existing memory entry."""
+    board = load_memory()
+    entry = _find_entry(board, entry_id)
+    if entry is None:
+        raise NotFoundError(
+            f"Memory entry '{entry_id}' not found",
+            hint="Run 'hoja memory list' to see available IDs.",
+        )
+    if title is not None:
+        entry.title = title
+    if body is not None:
+        entry.body = body
+    if priority is not None:
+        entry.priority = priority
+    entry.last_updated = __import__("hoja.memory_board", fromlist=["_now"])._now()
+    save_memory(board)
+    typer.echo(f"Updated memory '{entry_id}'")
+
+
+@memory_app.command("remove")
+def memory_remove(
+    entry_id: str = typer.Argument(..., help="Entry ID to remove"),
+) -> None:
+    """Remove a memory entry."""
+    board = load_memory()
+    removed = _remove_entry(board, entry_id)
+    if not removed:
+        raise NotFoundError(
+            f"Memory entry '{entry_id}' not found",
+            hint="Run 'hoja memory list' to see available IDs.",
+        )
+    save_memory(board)
+    typer.echo(f"Removed memory '{entry_id}'")
+
+
+@memory_app.command("heal")
+def memory_heal(
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be removed without deleting"),
+) -> None:
+    """Remove stale community entries (older than heal_after_days)."""
+    board = load_memory()
+    removed = heal(board)
+    if dry_run:
+        if removed:
+            typer.echo("Would remove:")
+            for rid in removed:
+                typer.echo(f"  - {rid}")
+        else:
+            typer.echo("Nothing to heal — all community entries are fresh.")
+        return
+    if removed:
+        save_memory(board)
+        typer.echo("Healed stale entries:")
+        for rid in removed:
+            typer.echo(f"  - {rid}")
+    else:
+        typer.echo("Nothing to heal — all community entries are fresh.")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _entry_dict(entry: MemoryEntry) -> dict[str, Any]:
+    return {
+        "id": entry.id,
+        "priority": entry.priority,
+        "title": entry.title,
+        "body": entry.body,
+        "created_by": entry.created_by,
+        "created_at": entry.created_at,
+        "last_updated": entry.last_updated,
+        "auto_heal": entry.auto_heal,
+        "heal_after_days": entry.heal_after_days,
+        "stale": _is_stale(entry),
+    }
+
+
+def _is_stale(entry: MemoryEntry) -> bool:
+    """Check if an entry is stale (for display purposes only)."""
+    if not entry.auto_heal or entry.heal_after_days <= 0:
+        return False
+    try:
+        from datetime import datetime, timezone
+        created = datetime.fromisoformat(entry.created_at)
+        age = datetime.now(timezone.utc) - created
+        return age.days > entry.heal_after_days
+    except (ValueError, TypeError):
+        return False
+
+
+def _slugify(text: str) -> str:
+    """Convert a title into a safe memory ID."""
+    import re
+    slug = re.sub(r"[^a-zA-Z0-9\s]", "", text).strip().lower()
+    slug = re.sub(r"\s+", "-", slug)
+    return slug[:40] or "memory"
+
+
+def _find_entry(board: MemoryBoard, entry_id: str) -> MemoryEntry | None:
+    for e in board.forced + board.community:
+        if e.id == entry_id:
+            return e
+    return None
+
+
+def _remove_entry(board: MemoryBoard, entry_id: str) -> bool:
+    for source in (board.forced, board.community):
+        for i, e in enumerate(source):
+            if e.id == entry_id:
+                source.pop(i)
+                return True
+    return False

hoja/commands/project.py

@@ -0,0 +1,56 @@
+"""`hoja project ...` commands."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+import typer
+
+from hoja.cli_state import build_client, get_state
+from hoja.graphql import queries
+from hoja.models.project import Project
+from hoja.output import render
+
+project_app = typer.Typer(help="Projects")
+
+
+@project_app.command("list")
+def list_projects(
+    state_filter: Optional[str] = typer.Option(
+        None, "--state", help="started|planned|completed|paused|backlog|canceled"
+    ),
+    limit: int = typer.Option(50, "--limit", "-n"),
+) -> None:
+    """List projects."""
+    asyncio.run(_run_list(state_filter, limit))
+
+
+@project_app.command("get")
+def get_project(id: str = typer.Argument(..., help="Project UUID")) -> None:
+    """Get a project by UUID."""
+    asyncio.run(_run_get(id))
+
+
+async def _run_list(state_filter: str | None, limit: int) -> None:
+    state = get_state()
+    filt: dict | None = None
+    if state_filter:
+        filt = {"state": {"eq": state_filter}}
+    async with build_client(state) as client:
+        projects = await client.execute_list(
+            Project, queries.PROJECTS_LIST,
+            {"filter": filt, "first": limit},
+            path=["projects"], operation="Projects",
+        )
+        render(projects, fmt=state.output, title="Projects")
+
+
+async def _run_get(id: str) -> None:
+    state = get_state()
+    async with build_client(state) as client:
+        project = await client.execute_as(
+            Project, queries.PROJECT_BY_ID, {"id": id},
+            path=["project"], operation="Project",
+        )
+        render(project, fmt=state.output, title=project.name)

hoja/commands/raw.py

@@ -0,0 +1,50 @@
+"""`hoja raw query ...` — escape hatch for arbitrary GraphQL."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from hoja.cli_state import build_client, get_state
+
+raw_app = typer.Typer(help="Escape hatch: arbitrary GraphQL")
+
+
+@raw_app.command("query")
+def raw_query(
+    query: Optional[str] = typer.Argument(None, help="GraphQL query string. If omitted, reads from stdin."),
+    file: Optional[Path] = typer.Option(None, "--file", "-f", help="Read query from file"),
+    variables: Optional[str] = typer.Option(None, "--variables", help="JSON variables"),
+    variables_file: Optional[Path] = typer.Option(None, "--variables-file", help="Read variables from JSON file"),
+) -> None:
+    """Execute an arbitrary GraphQL query/mutation."""
+    if file:
+        q = file.read_text()
+    elif query:
+        q = query
+    else:
+        q = sys.stdin.read()
+
+    if not q.strip():
+        typer.echo("error: empty query", err=True)
+        raise typer.Exit(2)
+
+    v: dict | None = None
+    if variables_file:
+        v = json.loads(variables_file.read_text())
+    elif variables:
+        v = json.loads(variables)
+
+    asyncio.run(_run(q, v))
+
+
+async def _run(query: str, variables: dict | None) -> None:
+    state = get_state()
+    async with build_client(state) as client:
+        data = await client.execute(query, variables)
+        print(json.dumps(data, indent=2, default=str))

hoja/commands/team.py

@@ -0,0 +1,102 @@
+"""`hoja team ...` commands."""
+
+from __future__ import annotations
+
+import asyncio
+
+import typer
+
+from hoja.cli_state import build_client, get_state
+from hoja.errors import NotFoundError
+from hoja.graphql import queries
+from hoja.models.team import Team
+from hoja.models.user import User
+from hoja.models.workflow import WorkflowState
+from hoja.output import render
+
+team_app = typer.Typer(help="Teams")
+
+
+@team_app.command("list")
+def list_teams() -> None:
+    """List all teams in the workspace."""
+    asyncio.run(_run_list())
+
+
+@team_app.command("get")
+def get_team(key: str = typer.Argument(..., help="Team key (e.g. ENG) or UUID")) -> None:
+    """Get a single team by key or id."""
+    asyncio.run(_run_get(key))
+
+
+@team_app.command("states")
+def team_states(
+    key: str = typer.Argument(..., help="Team key or UUID"),
+) -> None:
+    """List workflow states for a team."""
+    asyncio.run(_run_states(key))
+
+
+@team_app.command("members")
+def team_members(
+    key: str = typer.Argument(..., help="Team key or UUID"),
+) -> None:
+    """List members of a team."""
+    asyncio.run(_run_members(key))
+
+
+# ---------- runners ----------
+
+async def _resolve_team_id(client, key: str) -> str:
+    if len(key) == 36 and key.count("-") == 4:
+        return key
+    teams = await client.execute_list(
+        Team, queries.TEAM_BY_KEY, {"key": key.upper()},
+        path=["teams"], operation="TeamByKey",
+    )
+    if not teams:
+        raise NotFoundError(f"No team with key {key!r}")
+    return teams[0].id
+
+
+async def _run_list() -> None:
+    state = get_state()
+    async with build_client(state) as client:
+        teams = await client.execute_list(
+            Team, queries.TEAMS, path=["teams"], operation="Teams"
+        )
+        render(teams, fmt=state.output, title="Teams")
+
+
+async def _run_get(key: str) -> None:
+    state = get_state()
+    async with build_client(state) as client:
+        teams = await client.execute_list(
+            Team, queries.TEAM_BY_KEY, {"key": key.upper()},
+            path=["teams"], operation="TeamByKey",
+        )
+        if not teams:
+            raise NotFoundError(f"No team with key {key!r}")
+        render(teams[0], fmt=state.output)
+
+
+async def _run_states(key: str) -> None:
+    state = get_state()
+    async with build_client(state) as client:
+        team_id = await _resolve_team_id(client, key)
+        states = await client.execute_list(
+            WorkflowState, queries.TEAM_STATES, {"teamId": team_id},
+            path=["team", "states"], operation="TeamStates",
+        )
+        render(states, fmt=state.output, title=f"States for {key}")
+
+
+async def _run_members(key: str) -> None:
+    state = get_state()
+    async with build_client(state) as client:
+        team_id = await _resolve_team_id(client, key)
+        members = await client.execute_list(
+            User, queries.TEAM_MEMBERS, {"teamId": team_id},
+            path=["team", "members"], operation="TeamMembers",
+        )
+        render(members, fmt=state.output, title=f"Members of {key}")

hoja/commands/update.py

@@ -0,0 +1,162 @@
+"""`hoja update` — check PyPI and upgrade to the latest version."""
+
+from __future__ import annotations
+
+import json as _json
+import shutil
+import subprocess
+import sys
+import urllib.request
+from typing import Any
+
+import typer
+
+from hoja import DISTRIBUTION_NAME, __version__
+from hoja.cli_state import get_state
+from hoja.errors import UsageError
+from hoja.models.enums import OutputFormat
+
+update_app = typer.Typer(help="Update hoja to the latest version")
+
+
+PYPI_JSON_URL = f"https://pypi.org/pypi/{DISTRIBUTION_NAME}/json"
+
+
+@update_app.callback(invoke_without_command=True)
+def update(
+    ctx: typer.Context,
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would happen without upgrading"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+) -> None:
+    """Check PyPI for a newer version and upgrade hoja."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    state = get_state()
+    current = __version__
+
+    try:
+        latest = _fetch_latest_version()
+    except Exception as e:
+        if state.output == OutputFormat.JSON:
+            print(_json.dumps({"error": str(e), "current": current}, indent=2))
+        else:
+            typer.echo(f"Could not check for updates: {e}", err=True)
+        raise typer.Exit(1)
+
+    needs_update = _version_compare(current, latest) < 0
+
+    manager = _detect_package_manager()
+    if manager == "pipx":
+        cmd = ["pipx", "upgrade", DISTRIBUTION_NAME]
+    else:
+        cmd = [sys.executable, "-m", "pip", "install", "--upgrade", DISTRIBUTION_NAME]
+
+    result: dict[str, Any] = {
+        "current": current,
+        "latest": latest,
+        "needs_update": needs_update,
+        "manager": manager,
+        "command": " ".join(cmd),
+    }
+
+    if state.output == OutputFormat.JSON:
+        print(_json.dumps(result, indent=2))
+        if needs_update and not dry_run:
+            _run_upgrade(cmd, yes=yes)
+        return
+
+    # Human output
+    if not needs_update:
+        typer.echo(f"hoja is up to date (v{current})")
+        return
+
+    typer.echo(f"Current: v{current}")
+    typer.echo(f"Latest:  v{latest}")
+
+    if dry_run:
+        typer.echo(f"Would run: {' '.join(cmd)}")
+        return
+
+    if not yes:
+        confirmed = typer.confirm("Upgrade now?")
+        if not confirmed:
+            typer.echo("Aborted.")
+            raise typer.Exit(0)
+
+    _run_upgrade(cmd)
+
+
+def _fetch_latest_version() -> str:
+    """Query PyPI JSON API for the latest release version."""
+    req = urllib.request.Request(
+        PYPI_JSON_URL,
+        headers={"Accept": "application/json", "User-Agent": "hoja/update"},
+    )
+    with urllib.request.urlopen(req, timeout=10) as resp:  # noqa: S310
+        data = _json.load(resp)
+    info = data.get("info", {})
+    version = info.get("version")
+    if not version:
+        raise UsageError("Could not parse PyPI response", hint="Try again later.")
+    return version
+
+
+def _version_compare(a: str, b: str) -> int:
+    """Compare two PEP 440 version strings. Returns <0 if a < b, 0 if equal, >0 if a > b."""
+    # Simple tuple comparison for x.y.z (good enough for this CLI)
+    def _parse(v: str) -> tuple[int, ...]:
+        parts = v.split(".")
+        result: list[int] = []
+        for p in parts:
+            # Strip any suffix like "a1", "b2", "rc1", "dev0"
+            num = ""
+            for ch in p:
+                if ch.isdigit():
+                    num += ch
+                else:
+                    break
+            result.append(int(num) if num else 0)
+        return tuple(result)
+
+    pa = _parse(a)
+    pb = _parse(b)
+    for x, y in zip(pa, pb):
+        if x != y:
+            return x - y
+    return len(pa) - len(pb)
+
+
+def _detect_package_manager() -> str:
+    """Detect whether hoja was installed via pipx or pip."""
+    # Check if pipx is available and manages hoja
+    pipx_path = shutil.which("pipx")
+    if pipx_path:
+        try:
+            out = subprocess.run(
+                [pipx_path, "list", "--json"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=True,
+            )
+            data = _json.loads(out.stdout)
+            venvs = data.get("venvs", {})
+            # The current distribution is `hoja-cli`; `hoja` covers installs
+            # made with the pre-release name.
+            if DISTRIBUTION_NAME in venvs or "hoja" in venvs:
+                return "pipx"
+        except (subprocess.SubprocessError, _json.JSONDecodeError, FileNotFoundError):
+            pass
+    return "pip"
+
+
+def _run_upgrade(cmd: list[str], *, yes: bool = True) -> None:
+    """Execute the upgrade command."""
+    try:
+        subprocess.run(cmd, check=True)  # noqa: S603
+    except subprocess.CalledProcessError as e:
+        raise UsageError(
+            f"Upgrade failed (exit {e.returncode})",
+            hint="Try running the command manually: " + " ".join(cmd),
+        ) from e