stools-cli 0.1.0__py3-none-any.whl

stools_cli/__init__.py

@@ -0,0 +1 @@
+"""stools — CLI to extract structured data from Steam."""

stools_cli/cli.py

@@ -0,0 +1,244 @@
+"""stools — CLI to extract structured data from Steam.
+
+Usage:
+    stools search <query> [--limit <n>]
+    stools reviews <app_id_or_url> [--language <code>] [--limit <n>] [--output <file>]
+
+All output is JSON on stdout. Errors go to stderr.
+Exit codes: 0 = success, 1 = usage error, 2 = network/API error.
+"""
+
+import argparse
+import json
+import re
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+VERSION = "0.1.0"
+
+
+def pick_fields(items: list[dict], fields: list[str]) -> list[dict]:
+    """Keep only the specified keys from each dict in a list."""
+    picked = []
+    for item in items:
+        picked.append({k: item[k] for k in fields if k in item})
+    return picked
+
+
+def parse_app_id(value: str) -> int:
+    """Extract a Steam app ID from a store URL or plain integer string."""
+    match = re.search(r"store\.steampowered\.com/app/(\d+)", value)
+    if match:
+        return int(match.group(1))
+    if value.isdigit():
+        return int(value)
+    print(
+        json.dumps({"error": f"Cannot parse app ID from '{value}'. Provide a Steam store URL or numeric app ID."}),
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def fetch_reviews(app_id: int, language: str = "all", limit: int = 0) -> dict:
+    """Fetch reviews for a Steam app, paginating automatically."""
+    all_reviews: list[dict] = []
+    cursor = "*"
+    query_summary = None
+    per_page = 100
+
+    while True:
+        if limit and len(all_reviews) >= limit:
+            break
+
+        batch_size = min(per_page, limit - len(all_reviews)) if limit else per_page
+
+        params = urllib.parse.urlencode({
+            "json": 1,
+            "num_per_page": batch_size,
+            "cursor": cursor,
+            "filter": "recent",
+            "language": language,
+            "review_type": "all",
+            "purchase_type": "all",
+        })
+        url = f"https://store.steampowered.com/appreviews/{app_id}?{params}"
+
+        try:
+            req = urllib.request.Request(url, headers={"User-Agent": "stools/0.1.0"})
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                data = json.loads(resp.read().decode())
+        except urllib.error.URLError as e:
+            print(json.dumps({"error": f"Network error: {e}"}), file=sys.stderr)
+            sys.exit(2)
+
+        if data.get("success") != 1:
+            print(json.dumps({"error": "Steam API error. Verify the app ID exists."}), file=sys.stderr)
+            sys.exit(2)
+
+        if query_summary is None:
+            query_summary = data.get("query_summary", {})
+
+        reviews = data.get("reviews", [])
+        if not reviews:
+            break
+
+        all_reviews.extend(reviews)
+
+        cursor = data.get("cursor")
+        if not cursor:
+            break
+
+        time.sleep(0.5)
+
+    if limit:
+        all_reviews = all_reviews[:limit]
+
+    return {
+        "app_id": app_id,
+        "query_summary": query_summary,
+        "total_fetched": len(all_reviews),
+        "reviews": all_reviews,
+    }
+
+
+def fetch_search(query: str, limit: int = 10) -> dict:
+    """Search Steam for games matching a query."""
+    params = urllib.parse.urlencode({
+        "term": query,
+        "l": "english",
+        "cc": "US",
+    })
+    url = f"https://store.steampowered.com/api/storesearch/?{params}"
+
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "stools/0.1.0"})
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            data = json.loads(resp.read().decode())
+    except urllib.error.URLError as e:
+        print(json.dumps({"error": f"Network error: {e}"}), file=sys.stderr)
+        sys.exit(2)
+
+    items = data.get("items", [])[:limit]
+
+    results = []
+    for item in items:
+        results.append({
+            "app_id": item["id"],
+            "name": item["name"],
+            "price": item.get("price"),
+            "platforms": item.get("platforms"),
+            "metascore": item.get("metascore") or None,
+        })
+
+    return {
+        "query": query,
+        "total_results": data.get("total", 0),
+        "results": results,
+    }
+
+
+def cmd_search(args: argparse.Namespace) -> None:
+    result = fetch_search(args.query, limit=args.limit)
+    if args.fields:
+        result["results"] = pick_fields(result["results"], args.fields)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+def cmd_reviews(args: argparse.Namespace) -> None:
+    app_id = parse_app_id(args.app)
+    result = fetch_reviews(app_id, language=args.language, limit=args.limit)
+    if args.fields:
+        result["reviews"] = pick_fields(result["reviews"], args.fields)
+
+    output = json.dumps(result, indent=2, ensure_ascii=False)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(output + "\n")
+    else:
+        print(output)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="stools",
+        description="CLI to extract structured data from Steam. All output is JSON.",
+    )
+    parser.add_argument("--version", action="version", version=f"stools {VERSION}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # --- search subcommand ---
+    search_parser = subparsers.add_parser(
+        "search",
+        help="Search Steam for games matching a query.",
+        description=(
+            "Search for games on Steam by name. Returns a JSON object with fields: "
+            "query, total_results, results. Each result has: app_id, name, price, platforms, metascore."
+        ),
+    )
+    search_parser.add_argument(
+        "query",
+        help="Search term (e.g. 'megaman', 'dark souls', 'snake')",
+    )
+    search_parser.add_argument(
+        "--limit",
+        type=int,
+        default=10,
+        metavar="N",
+        help="Max results to return (default: 10)",
+    )
+    search_parser.add_argument(
+        "--fields",
+        type=lambda s: s.split(","),
+        metavar="f1,f2,...",
+        help="Comma-separated list of fields to keep per result. Available: app_id, name, price, platforms, metascore",
+    )
+    search_parser.set_defaults(func=cmd_search)
+
+    # --- reviews subcommand ---
+    reviews_parser = subparsers.add_parser(
+        "reviews",
+        help="Fetch all reviews for a Steam game as JSON.",
+        description=(
+            "Fetch reviews for a Steam game. Accepts a numeric app ID or a full Steam store URL. "
+            "Output is a JSON object with fields: app_id, query_summary, total_fetched, reviews."
+        ),
+    )
+    reviews_parser.add_argument(
+        "app",
+        help="Steam app ID (e.g. 1005310) or store URL (e.g. https://store.steampowered.com/app/1005310/Snake_vs_Snake/)",
+    )
+    reviews_parser.add_argument(
+        "--language",
+        default="all",
+        metavar="CODE",
+        help="Filter by language: english, spanish, french, german, etc. (default: all)",
+    )
+    reviews_parser.add_argument(
+        "--limit",
+        type=int,
+        default=0,
+        metavar="N",
+        help="Max number of reviews to fetch. 0 = all (default: 0)",
+    )
+    reviews_parser.add_argument(
+        "--output",
+        metavar="FILE",
+        help="Write JSON to FILE instead of stdout.",
+    )
+    reviews_parser.add_argument(
+        "--fields",
+        type=lambda s: s.split(","),
+        metavar="f1,f2,...",
+        help="Comma-separated list of fields to keep per review. Available: recommendationid, author, language, review, timestamp_created, timestamp_updated, voted_up, votes_up, votes_funny, steam_purchase, received_for_free, written_during_early_access",
+    )
+    reviews_parser.set_defaults(func=cmd_reviews)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

stools_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: stools-cli
+Version: 0.1.0
+Summary: CLI to extract structured data from Steam (reviews, game search) — designed for LLM agents
+Project-URL: Repository, https://github.com/aotarola/stools
+Author: aotarola
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cli,llm,reviews,steam
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# stools
+
+CLI tool to extract structured data from Steam. Outputs JSON to stdout, making it easy to pipe into other tools or consume from LLM agents.
+
+## Installation
+
+```bash
+pipx install stools-cli
+```
+
+Or with pip:
+
+```bash
+pip install stools-cli
+```
+
+Requires Python 3.9+. No external dependencies.
+
+## Commands
+
+### `stools search`
+
+Search Steam for games by name.
+
+```
+stools search <query> [--limit N] [--fields f1,f2,...]
+```
+
+| Argument      | Description                                              |
+|---------------|----------------------------------------------------------|
+| `query`       | Search term (e.g. `megaman`, `dark souls`)               |
+| `--limit N`   | Max results to return. Default: `10`                     |
+| `--fields`    | Comma-separated fields to keep per result (e.g. `app_id,name`) |
+
+#### Output schema
+
+```json
+{
+  "query": "megaman",
+  "total_results": 10,
+  "results": [
+    {
+      "app_id": 742300,
+      "name": "Mega Man 11",
+      "price": { "currency": "USD", "initial": 2999, "final": 2999 },
+      "platforms": { "windows": true, "mac": false, "linux": false },
+      "metascore": "80"
+    }
+  ]
+}
+```
+
+#### Examples
+
+```bash
+# Search for a game
+stools search "megaman"
+
+# Get top 3 results, only app_id and name
+stools search "dark souls" --limit 3 --fields app_id,name
+
+# Search then fetch reviews for the first result
+APP_ID=$(stools search "snake vs snake" 2>/dev/null | jq '.results[0].app_id')
+stools reviews "$APP_ID"
+```
+
+### `stools reviews`
+
+Fetch all reviews for a Steam game.
+
+```
+stools reviews <app_id_or_url> [--language CODE] [--limit N] [--fields f1,f2,...] [--output FILE]
+```
+
+| Argument       | Description                                                                 |
+|----------------|-----------------------------------------------------------------------------|
+| `app`          | Steam app ID (`1005310`) or store URL (`https://store.steampowered.com/app/1005310/Snake_vs_Snake/`) |
+| `--language`   | Filter by language code: `english`, `spanish`, `french`, `german`, etc. Default: `all` |
+| `--limit N`    | Max reviews to return. `0` = all. Default: `0`                              |
+| `--fields`     | Comma-separated fields to keep per review (e.g. `review,voted_up`)          |
+| `--output FILE`| Write JSON to a file instead of stdout                                      |
+
+#### Output schema
+
+```json
+{
+  "app_id": 1005310,
+  "query_summary": {
+    "num_reviews": 33,
+    "review_score": 7,
+    "review_score_desc": "Positive",
+    "total_positive": 33,
+    "total_negative": 0,
+    "total_reviews": 33
+  },
+  "total_fetched": 33,
+  "reviews": [
+    {
+      "recommendationid": "210668843",
+      "author": {
+        "steamid": "76561198079866033",
+        "personaname": "username",
+        "num_reviews": 32,
+        "playtime_forever": 1554,
+        "playtime_at_review": 1554
+      },
+      "language": "english",
+      "review": "Review text here.",
+      "timestamp_created": 1764106395,
+      "timestamp_updated": 1764106395,
+      "voted_up": true,
+      "votes_up": 0,
+      "votes_funny": 0,
+      "steam_purchase": true,
+      "received_for_free": false,
+      "written_during_early_access": false
+    }
+  ]
+}
+```
+
+#### Examples
+
+```bash
+# Fetch all reviews for a game
+stools reviews 1005310
+
+# Fetch only English reviews, save to file
+stools reviews 1005310 --language english --output reviews.json
+
+# Fetch first 10 reviews, no progress output
+stools reviews 1005310 --limit 10
+# Use a full Steam URL
+stools reviews "https://store.steampowered.com/app/1005310/Snake_vs_Snake/"
+
+# Get only review text and sentiment
+stools reviews 1005310 --fields review,voted_up
+```
+
+## Exit codes
+
+| Code | Meaning            |
+|------|--------------------|
+| `0`  | Success            |
+| `1`  | Usage / input error|
+| `2`  | Network / API error|
+
+## Agent integration
+
+stools ships as a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code). To use it in your agent:
+
+```bash
+claude install-plugin aotarola/stools
+```
+
+This registers the `stools` CLI as a skill that Claude Code can discover and invoke automatically. See [`skills/stools/SKILL.md`](skills/stools/SKILL.md) for the agent-facing documentation.
+
+## Design notes
+
+- **JSON only**: all output goes to stdout as JSON; errors go to stderr.
+- **No dependencies**: uses only Python standard library.
+- **Subcommand structure**: `stools <command>` — designed to grow with more Steam data commands.
+- **Agent-ready**: includes `.claude-plugin/` manifest and `skills/` for automatic discovery by LLM agents.

stools_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+stools_cli/__init__.py,sha256=LT52Axj4CBTcBuxxW_qLiRjM5hcgEjaj_7zNWnXrM30,60
+stools_cli/cli.py,sha256=WRiOxNpjc8_GUx_wLSDLvWN8SymHSD-yGYsDn3WJIwQ,7727
+stools_cli-0.1.0.dist-info/METADATA,sha256=qD3I_b6k5wYFDvLSAUH36vaDCgB6LiLSuac6gSGYNMo,5247
+stools_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+stools_cli-0.1.0.dist-info/entry_points.txt,sha256=aPwBZ98s-GreQKZ5KPrzsBUaTBGYUJQjcQEh1k2v2h0,47
+stools_cli-0.1.0.dist-info/licenses/LICENSE,sha256=ZSxT2w1FY7KtCoW08V3MUAaB4H8qKLp3rxBpAvt0SE4,1065
+stools_cli-0.1.0.dist-info/RECORD,,

stools_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

stools_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stools = stools_cli.cli:main

stools_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aotarola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.