npm - calvyn-code - Versions diffs - 0.14.0 - Mend

calvyn-code 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1718) hide show

package/skills/productivity/linear/scripts/linear_api.py ADDED Viewed

@@ -0,0 +1,445 @@
+#!/usr/bin/env python3
+"""Linear GraphQL API CLI — zero dependencies, stdlib only.
+Usage:
+  linear_api.py <command> [args...]
+Commands:
+  whoami                                  Show authenticated user
+  list-teams                              List all teams
+  list-projects [--team KEY]              List projects (optionally filter by team)
+  list-states [--team KEY]                List workflow states
+  list-issues [filters]                   List issues
+    --team KEY                            Filter by team key (e.g. ENG)
+    --status NAME                         Filter by workflow state name
+    --assignee NAME                       Filter by assignee name (exact)
+    --label NAME                          Filter by label name
+    --limit N                             Max results (default: 25)
+  get-issue <IDENTIFIER>                  Full issue details (e.g. ENG-42)
+  search-issues <query>                   Full-text search across issues
+  create-issue [options]                  Create a new issue
+    --title TITLE                         Required
+    --team KEY                            Required
+    --description DESC
+    --priority 0-4                        0=none, 1=urgent, 4=low
+    --label NAME
+    --assignee NAME
+    --parent IDENTIFIER                   Parent issue ID for sub-issues
+  update-issue <IDENTIFIER> [options]     Update existing issue (same options as create)
+  update-status <IDENTIFIER> <STATE>      Move issue to workflow state (by state name)
+  add-comment <IDENTIFIER> <body>         Add comment to issue
+  list-documents [--limit N]              List documents (docs, not issues)
+  get-document <SLUG_OR_ID>               Fetch a document by slugId (from URL) or UUID
+  search-documents <query>                Search documents by title
+  raw <graphql_query> [variables_json]    Run an arbitrary GraphQL query
+                                          Use --vars '{"key":"value"}' for variables
+Auth:
+  Set LINEAR_API_KEY environment variable (from Linear Settings -> API).
+  Uses the personal API key header format: `Authorization: <KEY>` (no Bearer prefix).
+Output:
+  JSON to stdout. Errors to stderr with non-zero exit code.
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from typing import Any
+API_URL = "https://api.linear.app/graphql"
+def _get_key() -> str:
+    key = os.environ.get("LINEAR_API_KEY", "").strip()
+    if not key:
+        sys.stderr.write(
+            "ERROR: LINEAR_API_KEY not set.\n"
+            "Create one at https://linear.app/settings/api and export it,\n"
+            "or add `LINEAR_API_KEY=lin_api_...` to ~/.hermes/.env\n"
+        )
+        sys.exit(2)
+    return key
+def gql(query: str, variables: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Execute a GraphQL query against Linear. Raises on HTTP error or GraphQL errors."""
+    key = _get_key()
+    payload = {"query": query}
+    if variables:
+        payload["variables"] = variables
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        API_URL,
+        data=data,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": key,  # Personal API key — NO `Bearer` prefix
+            "User-Agent": "hermes-agent-linear-skill/1.0",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            body = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        sys.stderr.write(f"HTTP {e.code}: {e.read().decode('utf-8', 'replace')}\n")
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        sys.stderr.write(f"Network error: {e}\n")
+        sys.exit(1)
+    result = json.loads(body)
+    if "errors" in result and result["errors"]:
+        sys.stderr.write(f"GraphQL errors: {json.dumps(result['errors'], indent=2)}\n")
+        # Still return data if partial success; let caller decide
+        if not result.get("data"):
+            sys.exit(1)
+    return result.get("data", {}) or {}
+def emit(obj: Any) -> None:
+    print(json.dumps(obj, indent=2, default=str))
+# ---------- Commands ----------
+def cmd_whoami(_args: argparse.Namespace) -> None:
+    q = "query { viewer { id name email displayName } }"
+    emit(gql(q).get("viewer"))
+def cmd_list_teams(_args: argparse.Namespace) -> None:
+    q = "query { teams(first: 100) { nodes { id key name description } } }"
+    emit(gql(q).get("teams", {}).get("nodes", []))
+def _resolve_team_id(key_or_name: str) -> str | None:
+    """Map a team key (ENG) or name to UUID."""
+    q = "query { teams(first: 100) { nodes { id key name } } }"
+    teams = gql(q).get("teams", {}).get("nodes", [])
+    kl = key_or_name.lower()
+    for t in teams:
+        if t["key"].lower() == kl or t["name"].lower() == kl:
+            return t["id"]
+    return None
+def cmd_list_projects(args: argparse.Namespace) -> None:
+    if args.team:
+        tid = _resolve_team_id(args.team)
+        if not tid:
+            sys.stderr.write(f"Team not found: {args.team}\n")
+            sys.exit(1)
+        q = """query($id: String!) {
+          team(id: $id) { projects(first: 100) { nodes { id name description state } } }
+        }"""
+        data = gql(q, {"id": tid})
+        emit(data.get("team", {}).get("projects", {}).get("nodes", []))
+    else:
+        q = "query { projects(first: 100) { nodes { id name description state } } }"
+        emit(gql(q).get("projects", {}).get("nodes", []))
+def cmd_list_states(args: argparse.Namespace) -> None:
+    if args.team:
+        tid = _resolve_team_id(args.team)
+        if not tid:
+            sys.stderr.write(f"Team not found: {args.team}\n")
+            sys.exit(1)
+        q = """query($id: String!) {
+          team(id: $id) { states(first: 100) { nodes { id name type color } } }
+        }"""
+        emit(gql(q, {"id": tid}).get("team", {}).get("states", {}).get("nodes", []))
+    else:
+        q = "query { workflowStates(first: 200) { nodes { id name type team { key } } } }"
+        emit(gql(q).get("workflowStates", {}).get("nodes", []))
+def cmd_list_issues(args: argparse.Namespace) -> None:
+    filt: dict[str, Any] = {}
+    if args.team:
+        filt["team"] = {"key": {"eq": args.team}}
+    if args.status:
+        filt["state"] = {"name": {"eq": args.status}}
+    if args.assignee:
+        filt["assignee"] = {"name": {"eq": args.assignee}}
+    if args.label:
+        filt["labels"] = {"name": {"eq": args.label}}
+    q = """query($filter: IssueFilter, $first: Int!) {
+      issues(filter: $filter, first: $first, orderBy: updatedAt) {
+        nodes {
+          id identifier title
+          state { name } priority
+          assignee { name }
+          team { key }
+          updatedAt url
+        }
+      }
+    }"""
+    data = gql(q, {"filter": filt or None, "first": args.limit})
+    emit(data.get("issues", {}).get("nodes", []))
+def cmd_get_issue(args: argparse.Namespace) -> None:
+    q = """query($id: String!) {
+      issue(id: $id) {
+        id identifier title description
+        state { name type }
+        priority priorityLabel
+        assignee { name email }
+        creator { name }
+        team { key name }
+        project { name }
+        labels { nodes { name } }
+        parent { identifier title }
+        children { nodes { identifier title state { name } } }
+        comments { nodes { user { name } body createdAt } }
+        createdAt updatedAt url
+      }
+    }"""
+    emit(gql(q, {"id": args.identifier}).get("issue"))
+def cmd_search_issues(args: argparse.Namespace) -> None:
+    q = """query($term: String!, $first: Int!) {
+      searchIssues(term: $term, first: $first) {
+        nodes { id identifier title state { name } url }
+      }
+    }"""
+    emit(gql(q, {"term": args.query, "first": args.limit}).get("searchIssues", {}).get("nodes", []))
+def cmd_create_issue(args: argparse.Namespace) -> None:
+    tid = _resolve_team_id(args.team)
+    if not tid:
+        sys.stderr.write(f"Team not found: {args.team}\n")
+        sys.exit(1)
+    inp: dict[str, Any] = {"title": args.title, "teamId": tid}
+    if args.description:
+        inp["description"] = args.description
+    if args.priority is not None:
+        inp["priority"] = args.priority
+    if args.parent:
+        inp["parentId"] = args.parent
+    # TODO: label + assignee name->id lookup (omitted for v1 brevity)
+    q = """mutation($input: IssueCreateInput!) {
+      issueCreate(input: $input) {
+        success issue { id identifier title url }
+      }
+    }"""
+    emit(gql(q, {"input": inp}).get("issueCreate"))
+def cmd_update_issue(args: argparse.Namespace) -> None:
+    inp: dict[str, Any] = {}
+    if args.title:
+        inp["title"] = args.title
+    if args.description:
+        inp["description"] = args.description
+    if args.priority is not None:
+        inp["priority"] = args.priority
+    if not inp:
+        sys.stderr.write("No update fields provided.\n")
+        sys.exit(1)
+    q = """mutation($id: String!, $input: IssueUpdateInput!) {
+      issueUpdate(id: $id, input: $input) {
+        success issue { identifier title url }
+      }
+    }"""
+    emit(gql(q, {"id": args.identifier, "input": inp}).get("issueUpdate"))
+def cmd_update_status(args: argparse.Namespace) -> None:
+    # Resolve state name -> id within the issue's team
+    get_q = """query($id: String!) {
+      issue(id: $id) { team { id states(first: 100) { nodes { id name } } } }
+    }"""
+    issue = gql(get_q, {"id": args.identifier}).get("issue")
+    if not issue:
+        sys.stderr.write(f"Issue not found: {args.identifier}\n")
+        sys.exit(1)
+    sl = args.state.lower()
+    match = next((s for s in issue["team"]["states"]["nodes"] if s["name"].lower() == sl), None)
+    if not match:
+        sys.stderr.write(
+            f"State '{args.state}' not found. Available: "
+            f"{[s['name'] for s in issue['team']['states']['nodes']]}\n"
+        )
+        sys.exit(1)
+    q = """mutation($id: String!, $stateId: String!) {
+      issueUpdate(id: $id, input: { stateId: $stateId }) {
+        success issue { identifier state { name } url }
+      }
+    }"""
+    emit(gql(q, {"id": args.identifier, "stateId": match["id"]}).get("issueUpdate"))
+def cmd_add_comment(args: argparse.Namespace) -> None:
+    q = """mutation($input: CommentCreateInput!) {
+      commentCreate(input: $input) {
+        success comment { id body createdAt }
+      }
+    }"""
+    emit(gql(q, {"input": {"issueId": args.identifier, "body": args.body}}).get("commentCreate"))
+# ---- Documents ----
+def cmd_list_documents(args: argparse.Namespace) -> None:
+    q = """query($first: Int!) {
+      documents(first: $first, orderBy: updatedAt) {
+        nodes { id title slugId updatedAt url project { name } creator { name } }
+      }
+    }"""
+    emit(gql(q, {"first": args.limit}).get("documents", {}).get("nodes", []))
+def cmd_get_document(args: argparse.Namespace) -> None:
+    """Fetch a document by slugId (from URL) OR full UUID.
+    Linear document URLs look like:
+      https://linear.app/<workspace>/document/<slug>-<shortid>
+    The part we want is the final hex segment (the slugId).
+    """
+    ref = args.ref
+    # If it looks like a UUID, query by id. Otherwise, assume slugId.
+    is_uuid = len(ref) == 36 and ref.count("-") == 4
+    if is_uuid:
+        q = """query($id: String!) {
+          document(id: $id) {
+            id title content contentState slugId
+            createdAt updatedAt url
+            creator { name } project { name }
+          }
+        }"""
+        emit(gql(q, {"id": ref}).get("document"))
+    else:
+        # Query the collection and filter by slugId — the doc() query only accepts UUIDs.
+        q = """query($slug: String!) {
+          documents(filter: { slugId: { eq: $slug } }, first: 1) {
+            nodes {
+              id title content contentState slugId
+              createdAt updatedAt url
+              creator { name } project { name }
+            }
+          }
+        }"""
+        nodes = gql(q, {"slug": ref}).get("documents", {}).get("nodes", [])
+        emit(nodes[0] if nodes else None)
+def cmd_search_documents(args: argparse.Namespace) -> None:
+    # Linear doesn't have a first-class searchDocuments — use title filter as a fallback.
+    q = """query($term: String!, $first: Int!) {
+      documents(filter: { title: { containsIgnoreCase: $term } }, first: $first) {
+        nodes { id title slugId url updatedAt }
+      }
+    }"""
+    emit(gql(q, {"term": args.query, "first": args.limit}).get("documents", {}).get("nodes", []))
+def cmd_raw(args: argparse.Namespace) -> None:
+    variables = json.loads(args.vars) if args.vars else None
+    emit(gql(args.query, variables))
+# ---------- Arg parsing ----------
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="linear_api.py", description="Linear GraphQL CLI")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("whoami").set_defaults(func=cmd_whoami)
+    sub.add_parser("list-teams").set_defaults(func=cmd_list_teams)
+    lp = sub.add_parser("list-projects")
+    lp.add_argument("--team")
+    lp.set_defaults(func=cmd_list_projects)
+    ls = sub.add_parser("list-states")
+    ls.add_argument("--team")
+    ls.set_defaults(func=cmd_list_states)
+    li = sub.add_parser("list-issues")
+    li.add_argument("--team")
+    li.add_argument("--status")
+    li.add_argument("--assignee")
+    li.add_argument("--label")
+    li.add_argument("--limit", type=int, default=25)
+    li.set_defaults(func=cmd_list_issues)
+    gi = sub.add_parser("get-issue")
+    gi.add_argument("identifier")
+    gi.set_defaults(func=cmd_get_issue)
+    si = sub.add_parser("search-issues")
+    si.add_argument("query")
+    si.add_argument("--limit", type=int, default=25)
+    si.set_defaults(func=cmd_search_issues)
+    ci = sub.add_parser("create-issue")
+    ci.add_argument("--title", required=True)
+    ci.add_argument("--team", required=True)
+    ci.add_argument("--description")
+    ci.add_argument("--priority", type=int, choices=[0, 1, 2, 3, 4])
+    ci.add_argument("--label")
+    ci.add_argument("--assignee")
+    ci.add_argument("--parent")
+    ci.set_defaults(func=cmd_create_issue)
+    ui = sub.add_parser("update-issue")
+    ui.add_argument("identifier")
+    ui.add_argument("--title")
+    ui.add_argument("--description")
+    ui.add_argument("--priority", type=int, choices=[0, 1, 2, 3, 4])
+    ui.set_defaults(func=cmd_update_issue)
+    us = sub.add_parser("update-status")
+    us.add_argument("identifier")
+    us.add_argument("state")
+    us.set_defaults(func=cmd_update_status)
+    ac = sub.add_parser("add-comment")
+    ac.add_argument("identifier")
+    ac.add_argument("body")
+    ac.set_defaults(func=cmd_add_comment)
+    ld = sub.add_parser("list-documents")
+    ld.add_argument("--limit", type=int, default=50)
+    ld.set_defaults(func=cmd_list_documents)
+    gd = sub.add_parser("get-document")
+    gd.add_argument("ref", help="slugId (hex suffix from URL) or full UUID")
+    gd.set_defaults(func=cmd_get_document)
+    sd = sub.add_parser("search-documents")
+    sd.add_argument("query")
+    sd.add_argument("--limit", type=int, default=25)
+    sd.set_defaults(func=cmd_search_documents)
+    r = sub.add_parser("raw")
+    r.add_argument("query")
+    r.add_argument("--vars", help="JSON string of variables")
+    r.set_defaults(func=cmd_raw)
+    return p
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)
+if __name__ == "__main__":
+    main()

package/skills/productivity/maps/SKILL.md ADDED Viewed

@@ -0,0 +1,195 @@
+---
+name: maps
+description: "Geocode, POIs, routes, timezones via OpenStreetMap/OSRM."
+version: 1.2.0
+author: Mibayy
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [maps, geocoding, places, routing, distance, directions, nearby, location, openstreetmap, nominatim, overpass, osrm]
+    category: productivity
+    requires_toolsets: [terminal]
+    supersedes: [find-nearby]
+---
+# Maps Skill
+Location intelligence using free, open data sources. 8 commands, 44 POI
+categories, zero dependencies (Python stdlib only), no API key required.
+Data sources: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.
+This skill supersedes the old `find-nearby` skill — all of find-nearby's
+functionality is covered by the `nearby` command below, with the same
+`--near "<place>"` shortcut and multi-category support.
+## When to Use
+- User sends a Telegram location pin (latitude/longitude in the message) → `nearby`
+- User wants coordinates for a place name → `search`
+- User has coordinates and wants the address → `reverse`
+- User asks for nearby restaurants, hospitals, pharmacies, hotels, etc. → `nearby`
+- User wants driving/walking/cycling distance or travel time → `distance`
+- User wants turn-by-turn directions between two places → `directions`
+- User wants timezone information for a location → `timezone`
+- User wants to search for POIs within a geographic area → `area` + `bbox`
+## Prerequisites
+Python 3.8+ (stdlib only — no pip installs needed).
+Script path: `~/.hermes/skills/maps/scripts/maps_client.py`
+## Commands
+```bash
+MAPS=~/.hermes/skills/maps/scripts/maps_client.py
+```
+### search — Geocode a place name
+```bash
+python3 $MAPS search "Eiffel Tower"
+python3 $MAPS search "1600 Pennsylvania Ave, Washington DC"
+```
+Returns: lat, lon, display name, type, bounding box, importance score.
+### reverse — Coordinates to address
+```bash
+python3 $MAPS reverse 48.8584 2.2945
+```
+Returns: full address breakdown (street, city, state, country, postcode).
+### nearby — Find places by category
+```bash
+# By coordinates (from a Telegram location pin, for example)
+python3 $MAPS nearby 48.8584 2.2945 restaurant --limit 10
+python3 $MAPS nearby 40.7128 -74.0060 hospital --radius 2000
+# By address / city / zip / landmark — --near auto-geocodes
+python3 $MAPS nearby --near "Times Square, New York" --category cafe
+python3 $MAPS nearby --near "90210" --category pharmacy
+# Multiple categories merged into one query
+python3 $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10
+```
+46 categories: restaurant, cafe, bar, hospital, pharmacy, hotel, guest_house,
+camp_site, supermarket, atm, gas_station, parking, museum, park, school,
+university, bank, police, fire_station, library, airport, train_station,
+bus_stop, church, mosque, synagogue, dentist, doctor, cinema, theatre, gym,
+swimming_pool, post_office, convenience_store, bakery, bookshop, laundry,
+car_wash, car_rental, bicycle_rental, taxi, veterinary, zoo, playground,
+stadium, nightclub.
+Each result includes: `name`, `address`, `lat`/`lon`, `distance_m`,
+`maps_url` (clickable Google Maps link), `directions_url` (Google Maps
+directions from the search point), and promoted tags when available —
+`cuisine`, `hours` (opening_hours), `phone`, `website`.
+### distance — Travel distance and time
+```bash
+python3 $MAPS distance "Paris" --to "Lyon"
+python3 $MAPS distance "New York" --to "Boston" --mode driving
+python3 $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking
+```
+Modes: driving (default), walking, cycling. Returns road distance, duration,
+and straight-line distance for comparison.
+### directions — Turn-by-turn navigation
+```bash
+python3 $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
+python3 $MAPS directions "JFK Airport" --to "Times Square" --mode driving
+```
+Returns numbered steps with instruction, distance, duration, road name, and
+maneuver type (turn, depart, arrive, etc.).
+### timezone — Timezone for coordinates
+```bash
+python3 $MAPS timezone 48.8584 2.2945
+python3 $MAPS timezone 35.6762 139.6503
+```
+Returns timezone name, UTC offset, and current local time.
+### area — Bounding box and area for a place
+```bash
+python3 $MAPS area "Manhattan, New York"
+python3 $MAPS area "London"
+```
+Returns bounding box coordinates, width/height in km, and approximate area.
+Useful as input for the bbox command.
+### bbox — Search within a bounding box
+```bash
+python3 $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20
+```
+Finds POIs within a geographic rectangle. Use `area` first to get the
+bounding box coordinates for a named place.
+## Working With Telegram Location Pins
+When a user sends a location pin, the message contains `latitude:` and
+`longitude:` fields. Extract those and pass them straight to `nearby`:
+```bash
+# User sent a pin at 36.17, -115.14 and asked "find cafes nearby"
+python3 $MAPS nearby 36.17 -115.14 cafe --radius 1500
+```
+Present results as a numbered list with names, distances, and the
+`maps_url` field so the user gets a tap-to-open link in chat. For "open
+now?" questions, check the `hours` field; if missing or unclear, verify
+with `web_search` since OSM hours are community-maintained and not always
+current.
+## Workflow Examples
+**"Find Italian restaurants near the Colosseum":**
+1. `nearby --near "Colosseum Rome" --category restaurant --radius 500`
+   — one command, auto-geocoded
+**"What's near this location pin they sent?":**
+1. Extract lat/lon from the Telegram message
+2. `nearby LAT LON cafe --radius 1500`
+**"How do I walk from hotel to conference center?":**
+1. `directions "Hotel Name" --to "Conference Center" --mode walking`
+**"What restaurants are in downtown Seattle?":**
+1. `area "Downtown Seattle"` → get bounding box
+2. `bbox S W N E restaurant --limit 30`
+## Pitfalls
+- Nominatim ToS: max 1 req/s (handled automatically by the script)
+- `nearby` requires lat/lon OR `--near "<address>"` — one of the two is needed
+- OSRM routing coverage is best for Europe and North America
+- Overpass API can be slow during peak hours; the script automatically
+  falls back between mirrors (overpass-api.de → overpass.kumi.systems)
+- `distance` and `directions` use `--to` flag for the destination (not positional)
+- If a zip code alone gives ambiguous results globally, include country/state
+## Verification
+```bash
+python3 ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
+# Should return lat ~40.689, lon ~-74.044
+python3 ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
+# Should return a list of restaurants within ~500m of Times Square
+```