hoja-cli 0.21.4__py3-none-any.whl

hoja/graphql/fragments.py

@@ -0,0 +1,138 @@
+"""Reusable GraphQL fragments.
+
+These keep our queries DRY and our model deserialization predictable —
+if a model expects a field, the fragment selects it.
+"""
+
+USER_CORE = """
+fragment UserCore on User {
+  id
+  name
+  displayName
+  email
+  active
+  isMe
+  avatarUrl
+}
+"""
+
+TEAM_CORE = """
+fragment TeamCore on Team {
+  id
+  name
+  key
+  description
+  color
+  icon
+  visibility
+  parentTeamId
+  timezone
+}
+"""
+
+STATE_CORE = """
+fragment StateCore on WorkflowState {
+  id
+  name
+  color
+  description
+  position
+  type
+}
+"""
+
+LABEL_CORE = """
+fragment LabelCore on IssueLabel {
+  id
+  name
+  color
+  description
+}
+"""
+
+PROJECT_CORE = """
+fragment ProjectCore on Project {
+  id
+  name
+  description
+  slugId
+  icon
+  color
+  state
+  progress
+  startDate
+  targetDate
+  url
+}
+"""
+
+CYCLE_CORE = """
+fragment CycleCore on Cycle {
+  id
+  name
+  number
+  startsAt
+  endsAt
+  completedAt
+  progress
+}
+"""
+
+ISSUE_CORE = """
+fragment IssueCore on Issue {
+  id
+  identifier
+  title
+  priority
+  priorityLabel
+  estimate
+  url
+  branchName
+  number
+  createdAt
+  updatedAt
+  dueDate
+  completedAt
+  canceledAt
+  startedAt
+  state { ...StateCore }
+  assignee { ...UserCore }
+  creator { ...UserCore }
+  team { id key name }
+}
+"""
+
+ISSUE_FULL = """
+fragment IssueFull on Issue {
+  ...IssueCore
+  description
+  project { ...ProjectCore }
+  cycle { ...CycleCore }
+  parent { id identifier title }
+  labels { nodes { ...LabelCore } }
+  subscribers { nodes { ...UserCore } }
+}
+"""
+
+PAGE_INFO = """
+fragment PageInfoCore on PageInfo {
+  hasNextPage
+  hasPreviousPage
+  startCursor
+  endCursor
+}
+"""
+
+
+def assemble(*fragments: str) -> str:
+    """Join a set of fragments deduplicating by name."""
+    seen: set[str] = set()
+    parts: list[str] = []
+    for frag in fragments:
+        # crude fragment name extraction
+        name = frag.split("fragment ", 1)[1].split(" ", 1)[0]
+        if name in seen:
+            continue
+        seen.add(name)
+        parts.append(frag.strip())
+    return "\n\n".join(parts)

hoja/graphql/mutations.py

@@ -0,0 +1,160 @@
+"""GraphQL mutation strings.
+
+Mutations that modify state. All return `success` and the affected entity
+so we can echo the result back to the user.
+"""
+
+from hoja.graphql.fragments import (
+    CYCLE_CORE,
+    ISSUE_CORE,
+    ISSUE_FULL,
+    LABEL_CORE,
+    PROJECT_CORE,
+    STATE_CORE,
+    USER_CORE,
+    assemble,
+)
+
+# ---------------------------------------------------------------------------
+# Issues
+# ---------------------------------------------------------------------------
+
+ISSUE_CREATE = (
+    """
+    mutation IssueCreate($input: IssueCreateInput!) {
+      issueCreate(input: $input) {
+        success
+        issue { ...IssueFull }
+      }
+    }
+    """
+    + assemble(ISSUE_FULL, ISSUE_CORE, USER_CORE, STATE_CORE, PROJECT_CORE, CYCLE_CORE, LABEL_CORE)
+)
+
+ISSUE_UPDATE = (
+    """
+    mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) {
+      issueUpdate(id: $id, input: $input) {
+        success
+        issue { ...IssueCore }
+      }
+    }
+    """
+    + assemble(ISSUE_CORE, USER_CORE, STATE_CORE)
+)
+
+ISSUE_DELETE = """
+    mutation IssueDelete($id: String!) {
+      issueDelete(id: $id) {
+        success
+      }
+    }
+    """
+
+ISSUE_ARCHIVE = """
+    mutation IssueArchive($id: String!) {
+      issueArchive(id: $id) {
+        success
+      }
+    }
+    """
+
+# ---------------------------------------------------------------------------
+# Comments
+# ---------------------------------------------------------------------------
+
+COMMENT_CREATE = """
+    mutation CommentCreate($input: CommentCreateInput!) {
+      commentCreate(input: $input) {
+        success
+        comment {
+          id
+          body
+          url
+          createdAt
+        }
+      }
+    }
+    """
+
+COMMENT_UPDATE = """
+    mutation CommentUpdate($id: String!, $input: CommentUpdateInput!) {
+      commentUpdate(id: $id, input: $input) {
+        success
+        comment {
+          id
+          body
+          url
+          updatedAt
+        }
+      }
+    }
+    """
+
+COMMENT_DELETE = """
+    mutation CommentDelete($id: String!) {
+      commentDelete(id: $id) {
+        success
+      }
+    }
+    """
+
+# ---------------------------------------------------------------------------
+# Labels
+# ---------------------------------------------------------------------------
+
+LABEL_CREATE = (
+    """
+    mutation LabelCreate($input: IssueLabelCreateInput!) {
+      issueLabelCreate(input: $input) {
+        success
+        issueLabel { ...LabelCore }
+      }
+    }
+    """
+    + assemble(LABEL_CORE)
+)
+
+LABEL_DELETE = """
+    mutation LabelDelete($id: String!) {
+      issueLabelDelete(id: $id) {
+        success
+      }
+    }
+    """
+
+# ---------------------------------------------------------------------------
+# Projects
+# ---------------------------------------------------------------------------
+
+PROJECT_CREATE = (
+    """
+    mutation ProjectCreate($input: ProjectCreateInput!) {
+      projectCreate(input: $input) {
+        success
+        project { ...ProjectCore }
+      }
+    }
+    """
+    + assemble(PROJECT_CORE)
+)
+
+PROJECT_UPDATE = (
+    """
+    mutation ProjectUpdate($id: String!, $input: ProjectUpdateInput!) {
+      projectUpdate(id: $id, input: $input) {
+        success
+        project { ...ProjectCore }
+      }
+    }
+    """
+    + assemble(PROJECT_CORE)
+)
+
+PROJECT_ARCHIVE = """
+    mutation ProjectArchive($id: String!) {
+      projectArchive(id: $id) {
+        success
+      }
+    }
+    """

hoja/graphql/queries.py

@@ -0,0 +1,245 @@
+"""GraphQL query strings.
+
+These return read-only data. Each query template includes the fragments
+it needs at the bottom.
+"""
+
+from hoja.graphql.fragments import (
+    CYCLE_CORE,
+    ISSUE_CORE,
+    ISSUE_FULL,
+    LABEL_CORE,
+    PAGE_INFO,
+    PROJECT_CORE,
+    STATE_CORE,
+    TEAM_CORE,
+    USER_CORE,
+    assemble,
+)
+
+# ---------------------------------------------------------------------------
+# Viewer / Me
+# ---------------------------------------------------------------------------
+
+VIEWER = (
+    """
+    query Viewer {
+      viewer {
+        ...UserCore
+        admin
+        url
+        timezone
+        statusEmoji
+        statusLabel
+      }
+    }
+    """
+    + assemble(USER_CORE)
+)
+
+# ---------------------------------------------------------------------------
+# Teams
+# ---------------------------------------------------------------------------
+
+TEAMS = (
+    """
+    query Teams($first: Int = 50, $after: String) {
+      teams(first: $first, after: $after) {
+        nodes { ...TeamCore }
+        pageInfo { ...PageInfoCore }
+      }
+    }
+    """
+    + assemble(TEAM_CORE, PAGE_INFO)
+)
+
+TEAM_BY_KEY = (
+    """
+    query TeamByKey($key: String!) {
+      teams(filter: { key: { eq: $key } }, first: 1) {
+        nodes { ...TeamCore }
+      }
+    }
+    """
+    + assemble(TEAM_CORE)
+)
+
+TEAM_STATES = (
+    """
+    query TeamStates($teamId: String!) {
+      team(id: $teamId) {
+        id
+        key
+        name
+        states {
+          nodes { ...StateCore }
+        }
+      }
+    }
+    """
+    + assemble(STATE_CORE)
+)
+
+TEAM_MEMBERS = (
+    """
+    query TeamMembers($teamId: String!, $first: Int = 100) {
+      team(id: $teamId) {
+        id
+        key
+        name
+        members(first: $first) {
+          nodes { ...UserCore }
+        }
+      }
+    }
+    """
+    + assemble(USER_CORE)
+)
+
+# ---------------------------------------------------------------------------
+# Issues
+# ---------------------------------------------------------------------------
+
+ISSUES_LIST = (
+    """
+    query Issues($filter: IssueFilter, $first: Int = 50, $after: String, $orderBy: PaginationOrderBy) {
+      issues(filter: $filter, first: $first, after: $after, orderBy: $orderBy) {
+        nodes { ...IssueCore }
+        pageInfo { ...PageInfoCore }
+      }
+    }
+    """
+    + assemble(ISSUE_CORE, USER_CORE, STATE_CORE, PAGE_INFO)
+)
+
+ISSUE_BY_IDENTIFIER = (
+    """
+    query IssueByIdentifier($id: String!) {
+      issue(id: $id) {
+        ...IssueFull
+      }
+    }
+    """
+    + assemble(ISSUE_FULL, ISSUE_CORE, USER_CORE, STATE_CORE, PROJECT_CORE, CYCLE_CORE, LABEL_CORE)
+)
+
+# ---------------------------------------------------------------------------
+# Projects
+# ---------------------------------------------------------------------------
+
+PROJECTS_LIST = (
+    """
+    query Projects($filter: ProjectFilter, $first: Int = 50, $after: String) {
+      projects(filter: $filter, first: $first, after: $after) {
+        nodes { ...ProjectCore }
+        pageInfo { ...PageInfoCore }
+      }
+    }
+    """
+    + assemble(PROJECT_CORE, PAGE_INFO)
+)
+
+PROJECT_BY_ID = (
+    """
+    query Project($id: String!) {
+      project(id: $id) {
+        ...ProjectCore
+        lead { ...UserCore }
+        creator { ...UserCore }
+        members { nodes { ...UserCore } }
+      }
+    }
+    """
+    + assemble(PROJECT_CORE, USER_CORE)
+)
+
+# ---------------------------------------------------------------------------
+# Cycles
+# ---------------------------------------------------------------------------
+
+TEAM_CYCLES = (
+    """
+    query TeamCycles($teamId: String!, $first: Int = 20) {
+      team(id: $teamId) {
+        id
+        key
+        cycles(first: $first) {
+          nodes { ...CycleCore }
+        }
+        activeCycle { ...CycleCore }
+      }
+    }
+    """
+    + assemble(CYCLE_CORE)
+)
+
+# ---------------------------------------------------------------------------
+# Comments
+# ---------------------------------------------------------------------------
+
+ISSUE_COMMENTS = (
+    """
+    query IssueComments($issueId: String!, $first: Int = 50) {
+      issue(id: $issueId) {
+        id
+        identifier
+        comments(first: $first) {
+          nodes {
+            id
+            body
+            url
+            createdAt
+            updatedAt
+            user { ...UserCore }
+          }
+        }
+      }
+    }
+    """
+    + assemble(USER_CORE)
+)
+
+# ---------------------------------------------------------------------------
+# Workflow / Labels
+# ---------------------------------------------------------------------------
+
+ISSUE_LABELS = (
+    """
+    query IssueLabels($filter: IssueLabelFilter, $first: Int = 100) {
+      issueLabels(filter: $filter, first: $first) {
+        nodes { ...LabelCore }
+      }
+    }
+    """
+    + assemble(LABEL_CORE)
+)
+
+# ---------------------------------------------------------------------------
+# Search
+# ---------------------------------------------------------------------------
+
+# searchIssues returns IssueSearchResult which extends Issue with metadata.
+# We use inline fragment to spread Issue fields onto IssueSearchResult.
+SEARCH_ISSUES = (
+    """
+    query SearchIssues($term: String!, $first: Int = 20) {
+      searchIssues(term: $term, first: $first) {
+        nodes {
+          id
+          identifier
+          title
+          priority
+          priorityLabel
+          url
+          number
+          createdAt
+          updatedAt
+          state { ...StateCore }
+          assignee { ...UserCore }
+          team { id key name }
+        }
+      }
+    }
+    """
+    + assemble(USER_CORE, STATE_CORE)
+)

hoja/mcp/__init__.py

@@ -0,0 +1,27 @@
+"""MCP server for Hoja.
+
+This package is **optional**. Install with:
+
+    pip install 'hoja[mcp]'
+
+The server exposes:
+  - 1 tool:       hoja_guide(topic)
+  - 7 resources:  read-only workspace context
+  - 6 prompts:    workflow templates (triage, daily-standup, hand-off, ...)
+
+It does NOT expose mutation tools by design. Mutations are performed via the
+`hoja` CLI in a shell — that's the supported interface and the agent is
+reinforced to use Bash for any write operation.
+
+Entry point: `hoja-mcp` (console script). See `server.main()`.
+"""
+
+
+def main() -> None:
+    """Run the MCP server without importing it during package initialization."""
+    from .server import main as server_main
+
+    server_main()
+
+
+__all__ = ["main"]

hoja/mcp/content.py

@@ -0,0 +1,151 @@
+"""Skill content loader + Pydantic model for the `hoja_guide` MCP tool.
+
+Loads the canonical markdown files from `hoja/skill_content/*.md` (shipped
+inside the wheel via `[tool.hatch.build.targets.wheel.force-include]`).
+"""
+from __future__ import annotations
+
+from enum import Enum
+from importlib.resources import files
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Topic enum — kebab-case in protocol, snake_case in Python
+# ---------------------------------------------------------------------------
+class Topic(str, Enum):
+    """Skill topics. String values match the markdown filenames (no extension)."""
+
+    OVERVIEW = "overview"
+    COMMANDS = "commands"
+    WORKFLOWS = "workflows"
+    FILTERS = "filters"
+    OUTPUT_FORMATS = "output-formats"
+    EXAMPLES = "examples"
+
+
+# ---------------------------------------------------------------------------
+# Pydantic response model for the MCP tool
+# ---------------------------------------------------------------------------
+DEFAULT_REMINDER = (
+    "Run hoja commands via the Bash tool. Do NOT write Python wrappers "
+    "around the Linear GraphQL API — Hoja already handles auth, retries, "
+    "pagination, validation, and error mapping. Resources on this MCP server "
+    "give you read-only context for free; perform every mutation via "
+    "`hoja <command>` in a shell."
+)
+
+
+class HojaGuide(BaseModel):
+    """Structured response for the `hoja_guide` tool.
+
+    The agent that calls this tool sees:
+      - `instructions`: full markdown content for the requested topic
+      - `key_commands`: a short hot-list of one-liners
+      - `see_also`: other topics worth reading
+      - `reminder`: the behavioral reinforcement string (shown on every reply)
+    """
+
+    topic: Topic = Field(description="Which topic this guide covers.")
+    title: str = Field(description="Human-readable title for the topic.")
+    instructions: str = Field(
+        description="Markdown instructions teaching the agent how to use Hoja for this topic.",
+    )
+    key_commands: list[str] = Field(
+        default_factory=list,
+        description="One-liner shell commands the agent should know.",
+    )
+    see_also: list[Topic] = Field(
+        default_factory=list,
+        description="Other topics linked from this one.",
+    )
+    reminder: str = Field(
+        default=DEFAULT_REMINDER,
+        description="Behavioral reminder. Read it on every response.",
+    )
+
+
+# Deprecated public model alias for one compatibility release.
+
+
+# ---------------------------------------------------------------------------
+# Content loading
+# ---------------------------------------------------------------------------
+def _content_dir() -> Path:
+    """Locate the bundled skill_content directory inside the installed package."""
+    return Path(str(files("hoja").joinpath("skill_content")))
+
+
+def _read_topic_file(topic: Topic) -> str:
+    """Read the markdown file for a topic. Raises FileNotFoundError if missing."""
+    path = _content_dir() / f"{topic.value}.md"
+    return path.read_text(encoding="utf-8")
+
+
+def _extract_title(markdown: str, fallback: str) -> str:
+    """Pull the first `# heading` from the markdown body."""
+    for line in markdown.splitlines():
+        s = line.strip()
+        if s.startswith("# "):
+            return s[2:].strip()
+    return fallback
+
+
+def _extract_key_commands(markdown: str, limit: int = 10) -> list[str]:
+    """Grab the first N `hoja ...` one-liners that look like bash commands.
+
+    Heuristic: scan fenced ```bash blocks, collect lines starting with `hoja `.
+    Skip comment lines and empty lines. Deduplicate while preserving order.
+    """
+    out: list[str] = []
+    seen: set[str] = set()
+    in_block = False
+    is_bash = False
+    for raw in markdown.splitlines():
+        line = raw.rstrip()
+        if line.startswith("```"):
+            if in_block:
+                in_block = False
+                is_bash = False
+            else:
+                in_block = True
+                # Detect language tag (```bash, ```sh, ```shell) or untagged blocks
+                tag = line.removeprefix("```").strip().lower()
+                is_bash = tag in {"", "bash", "sh", "shell"}
+            continue
+        if not in_block or not is_bash:
+            continue
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.startswith("hoja ") and stripped not in seen:
+            seen.add(stripped)
+            out.append(stripped)
+            if len(out) >= limit:
+                return out
+    return out
+
+
+def _see_also_for(topic: Topic) -> list[Topic]:
+    """Static cross-link map. Mirrors the 'See also' sections in the markdown."""
+    base = [t for t in Topic if t is not topic]
+    return base
+
+
+def load_topic(topic: Topic) -> HojaGuide:
+    """Load a topic's full guide.
+
+    Returns a Pydantic-validated `HojaGuide` ready to be returned from the
+    MCP tool. The MCP SDK will auto-serialize to JSON for the wire.
+    """
+    body = _read_topic_file(topic)
+    title = _extract_title(body, fallback=f"Hoja — {topic.value}")
+    return HojaGuide(
+        topic=topic,
+        title=title,
+        instructions=body,
+        key_commands=_extract_key_commands(body),
+        see_also=_see_also_for(topic),
+    )