cli-web-hackernews 0.1.0__py3-none-any.whl

cli_web/hackernews/README.md

@@ -0,0 +1,91 @@
+# cli-web-hackernews
+
+CLI for browsing and interacting with Hacker News — top stories, search, comments, user profiles, plus auth-enabled actions (upvote, submit, comment, favorite).
+
+## Installation
+
+```bash
+cd hackernews/agent-harness
+pip install -e .
+```
+
+## Usage
+
+### Browse (no auth required)
+
+```bash
+# Browse stories
+cli-web-hackernews stories top              # Front page (top 30)
+cli-web-hackernews stories new -n 10        # Newest 10 stories
+cli-web-hackernews stories best             # Best stories (all time)
+cli-web-hackernews stories ask              # Ask HN
+cli-web-hackernews stories show             # Show HN
+cli-web-hackernews stories jobs             # Job listings
+
+# View a story with comments
+cli-web-hackernews stories view 47530330
+cli-web-hackernews stories view 47530330 -n 5 --json
+
+# Search
+cli-web-hackernews search stories "claude code"
+cli-web-hackernews search comments "react hooks" --sort-date -n 5
+
+# User profiles
+cli-web-hackernews user view dang
+cli-web-hackernews user view pg --json
+```
+
+### Auth-Enabled Actions
+
+```bash
+# Login
+cli-web-hackernews auth login               # Username/password prompt
+cli-web-hackernews auth login-browser       # Login via browser window
+cli-web-hackernews auth status              # Check login status
+cli-web-hackernews auth logout              # Remove credentials
+
+# Interact (requires login)
+cli-web-hackernews upvote 47530330          # Upvote a story
+cli-web-hackernews submit -t "My Title" -u "https://example.com"  # Submit link
+cli-web-hackernews submit -t "Ask HN: Question?" --text "Details" # Ask HN
+cli-web-hackernews comment 47530330 "Great article!"              # Comment
+cli-web-hackernews favorite 47530330        # Save to favorites
+cli-web-hackernews hide 47530330            # Hide from feed
+
+# View your activity
+cli-web-hackernews user favorites           # Your favorites
+cli-web-hackernews user submissions         # Your submissions
+cli-web-hackernews user threads             # Replies to your comments
+cli-web-hackernews user submissions dang    # Someone else's submissions
+```
+
+### JSON output
+
+Every command supports `--json` for structured output:
+
+```bash
+cli-web-hackernews stories top -n 5 --json
+cli-web-hackernews upvote 47530330 --json
+cli-web-hackernews --json  # Propagates to all commands in REPL mode
+```
+
+### REPL mode
+
+Run without arguments to enter interactive mode:
+
+```bash
+cli-web-hackernews
+```
+
+## API Sources
+
+- **Firebase API**: `hacker-news.firebaseio.com/v0/` — stories, items, users (public)
+- **Algolia API**: `hn.algolia.com/api/v1/` — full-text search (public)
+- **HN Web**: `news.ycombinator.com` — auth actions (upvote, submit, comment, favorite, hide)
+
+## Testing
+
+```bash
+cd hackernews/agent-harness
+python -m pytest cli_web/hackernews/tests/ -v -s
+```

cli_web/hackernews/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as: python -m cli_web.hackernews"""
+
+from cli_web.hackernews.hackernews_cli import main
+
+if __name__ == "__main__":
+    main()

cli_web/hackernews/commands/actions.py

@@ -0,0 +1,105 @@
+"""Actions command group — upvote, submit, comment, favorite, hide (auth required)."""
+
+from __future__ import annotations
+
+import click
+from cli_web.hackernews.core import auth
+from cli_web.hackernews.core.client import HackerNewsClient
+from cli_web.hackernews.utils.helpers import handle_errors, print_json, resolve_json_mode
+
+
+def _auth_client() -> HackerNewsClient:
+    """Create an authenticated client."""
+    cookie = auth.get_user_cookie()
+    return HackerNewsClient(user_cookie=cookie)
+
+
+@click.command("upvote")
+@click.argument("item_id", type=int)
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def upvote_cmd(ctx, item_id, json_mode):
+    """Upvote a story or comment by ID. (Requires auth)"""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = _auth_client()
+        result = client.upvote(item_id)
+        if json_mode:
+            print_json(result)
+        else:
+            click.echo(f"Upvoted item {item_id}")
+
+
+@click.command("submit")
+@click.option("--title", "-t", required=True, help="Story title.")
+@click.option("--url", "-u", default=None, help="URL to submit (leave blank for Ask HN).")
+@click.option("--text", default=None, help="Text body (for Ask HN or to add context).")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def submit_cmd(ctx, title, url, text, json_mode):
+    """Submit a new story to Hacker News. (Requires auth)
+
+    Use --url for link submissions, or leave blank for Ask HN (text only).
+    """
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = _auth_client()
+        result = client.submit_story(title=title, url=url, text=text)
+        if json_mode:
+            print_json(result)
+        else:
+            kind = "link" if url else "Ask HN"
+            click.echo(f"Submitted {kind}: {title}")
+
+
+@click.command("comment")
+@click.argument("parent_id", type=int)
+@click.argument("text")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def comment_cmd(ctx, parent_id, text, json_mode):
+    """Post a comment on a story or reply to a comment. (Requires auth)
+
+    PARENT_ID is the story or comment ID to reply to.
+    TEXT is the comment body.
+    """
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = _auth_client()
+        result = client.post_comment(parent_id=parent_id, text=text)
+        if json_mode:
+            print_json(result)
+        else:
+            click.echo(f"Comment posted on item {parent_id}")
+
+
+@click.command("favorite")
+@click.argument("item_id", type=int)
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def favorite_cmd(ctx, item_id, json_mode):
+    """Favorite (save) a story. (Requires auth)"""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = _auth_client()
+        result = client.favorite(item_id)
+        if json_mode:
+            print_json(result)
+        else:
+            click.echo(f"Favorited item {item_id}")
+
+
+@click.command("hide")
+@click.argument("item_id", type=int)
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def hide_cmd(ctx, item_id, json_mode):
+    """Hide a story from your feed. (Requires auth)"""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = _auth_client()
+        result = client.hide(item_id)
+        if json_mode:
+            print_json(result)
+        else:
+            click.echo(f"Hidden item {item_id}")

cli_web/hackernews/commands/auth.py

@@ -0,0 +1,80 @@
+"""Auth command group — login, status, logout."""
+
+from __future__ import annotations
+
+import click
+from cli_web.hackernews.core import auth
+from cli_web.hackernews.utils.helpers import handle_errors, print_json, resolve_json_mode
+
+
+@click.group("auth")
+def auth_group():
+    """Manage Hacker News authentication."""
+
+
+@auth_group.command("login")
+@click.option("--username", "-u", prompt="HN username", help="Your Hacker News username.")
+@click.option("--password", "-p", prompt=True, hide_input=True, help="Your Hacker News password.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def auth_login(ctx, username, password, json_mode):
+    """Login to Hacker News with username and password."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        result = auth.login_with_password(username, password)
+        if json_mode:
+            print_json({"success": True, "username": result["username"]})
+        else:
+            click.echo(f"Logged in as {result['username']}")
+
+
+@auth_group.command("login-browser")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def auth_login_browser(ctx, json_mode):
+    """Login to Hacker News via browser (opens a browser window)."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        result = auth.login_browser()
+        if json_mode:
+            print_json({"success": True, "username": result["username"]})
+        else:
+            click.echo(f"Logged in as {result['username']}")
+
+
+@auth_group.command("status")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def auth_status(ctx, json_mode):
+    """Check authentication status."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        if not auth.is_logged_in():
+            if json_mode:
+                print_json({"logged_in": False})
+            else:
+                click.echo("Not logged in. Run: cli-web-hackernews auth login")
+            return
+
+        result = auth.validate_auth()
+        if json_mode:
+            print_json(
+                {"logged_in": True, "username": result["username"], "valid": result["valid"]}
+            )
+        else:
+            click.echo(f"Logged in as: {result['username']}")
+            click.echo(f"Cookie valid: {'yes' if result['valid'] else 'no'}")
+
+
+@auth_group.command("logout")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def auth_logout(ctx, json_mode):
+    """Remove stored authentication credentials."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        auth.logout()
+        if json_mode:
+            print_json({"success": True, "message": "Logged out"})
+        else:
+            click.echo("Logged out successfully.")

cli_web/hackernews/commands/search.py

@@ -0,0 +1,69 @@
+"""Search command — search HN via Algolia API."""
+
+from __future__ import annotations
+
+import click
+from cli_web.hackernews.core.client import HackerNewsClient
+from cli_web.hackernews.utils.helpers import handle_errors, resolve_json_mode
+from cli_web.hackernews.utils.output import print_json, print_search_results_table
+
+
+@click.group("search")
+def search_group():
+    """Search Hacker News stories and comments."""
+
+
+@search_group.command("stories")
+@click.argument("query")
+@click.option("-n", "--limit", default=20, show_default=True, help="Number of results.")
+@click.option("--page", default=0, help="Page number (0-indexed).")
+@click.option("--sort-date", is_flag=True, help="Sort by date instead of relevance.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def search_stories(ctx, query, limit, page, sort_date, json_mode):
+    """Search for stories by keyword."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        results = client.search(
+            query=query,
+            tags="story",
+            sort_by_date=sort_date,
+            hits_per_page=limit,
+            page=page,
+        )
+        if json_mode:
+            print_json([r.to_dict() for r in results])
+        else:
+            sort_label = "by date" if sort_date else "by relevance"
+            click.echo(f"\nSearch: '{query}' ({sort_label})\n")
+            print_search_results_table(results)
+            click.echo(f"\n{len(results)} results\n")
+
+
+@search_group.command("comments")
+@click.argument("query")
+@click.option("-n", "--limit", default=20, show_default=True, help="Number of results.")
+@click.option("--page", default=0, help="Page number (0-indexed).")
+@click.option("--sort-date", is_flag=True, help="Sort by date instead of relevance.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def search_comments(ctx, query, limit, page, sort_date, json_mode):
+    """Search for comments by keyword."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        results = client.search(
+            query=query,
+            tags="comment",
+            sort_by_date=sort_date,
+            hits_per_page=limit,
+            page=page,
+        )
+        if json_mode:
+            print_json([r.to_dict() for r in results])
+        else:
+            sort_label = "by date" if sort_date else "by relevance"
+            click.echo(f"\nSearch comments: '{query}' ({sort_label})\n")
+            print_search_results_table(results)
+            click.echo(f"\n{len(results)} results\n")

cli_web/hackernews/commands/stories.py

@@ -0,0 +1,160 @@
+"""Stories command group — browse HN feeds (top, new, best, ask, show, job)."""
+
+from __future__ import annotations
+
+import click
+from cli_web.hackernews.core.client import HackerNewsClient
+from cli_web.hackernews.utils.helpers import handle_errors, resolve_json_mode
+from cli_web.hackernews.utils.output import (
+    print_comments_list,
+    print_json,
+    print_stories_table,
+)
+
+
+@click.group("stories")
+def stories_group():
+    """Browse Hacker News stories."""
+
+
+@stories_group.command("top")
+@click.option("-n", "--limit", default=30, show_default=True, help="Number of stories to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def stories_top(ctx, limit, json_mode):
+    """Show top stories from the front page."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        stories = client.get_stories("top", limit=limit)
+        if json_mode:
+            print_json([s.to_dict() for s in stories])
+        else:
+            click.echo("\nTop Stories\n")
+            print_stories_table(stories)
+            click.echo(f"\n{len(stories)} stories\n")
+
+
+@stories_group.command("new")
+@click.option("-n", "--limit", default=30, show_default=True, help="Number of stories to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def stories_new(ctx, limit, json_mode):
+    """Show newest stories."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        stories = client.get_stories("new", limit=limit)
+        if json_mode:
+            print_json([s.to_dict() for s in stories])
+        else:
+            click.echo("\nNew Stories\n")
+            print_stories_table(stories)
+            click.echo(f"\n{len(stories)} stories\n")
+
+
+@stories_group.command("best")
+@click.option("-n", "--limit", default=30, show_default=True, help="Number of stories to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def stories_best(ctx, limit, json_mode):
+    """Show best stories (all time)."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        stories = client.get_stories("best", limit=limit)
+        if json_mode:
+            print_json([s.to_dict() for s in stories])
+        else:
+            click.echo("\nBest Stories\n")
+            print_stories_table(stories)
+            click.echo(f"\n{len(stories)} stories\n")
+
+
+@stories_group.command("ask")
+@click.option("-n", "--limit", default=30, show_default=True, help="Number of stories to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def stories_ask(ctx, limit, json_mode):
+    """Show Ask HN stories."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        stories = client.get_stories("ask", limit=limit)
+        if json_mode:
+            print_json([s.to_dict() for s in stories])
+        else:
+            click.echo("\nAsk HN\n")
+            print_stories_table(stories)
+            click.echo(f"\n{len(stories)} stories\n")
+
+
+@stories_group.command("show")
+@click.option("-n", "--limit", default=30, show_default=True, help="Number of stories to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def stories_show(ctx, limit, json_mode):
+    """Show Show HN stories."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        stories = client.get_stories("show", limit=limit)
+        if json_mode:
+            print_json([s.to_dict() for s in stories])
+        else:
+            click.echo("\nShow HN\n")
+            print_stories_table(stories)
+            click.echo(f"\n{len(stories)} stories\n")
+
+
+@stories_group.command("jobs")
+@click.option("-n", "--limit", default=30, show_default=True, help="Number of stories to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def stories_jobs(ctx, limit, json_mode):
+    """Show job stories."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        stories = client.get_stories("job", limit=limit)
+        if json_mode:
+            print_json([s.to_dict() for s in stories])
+        else:
+            click.echo("\nJobs\n")
+            print_stories_table(stories)
+            click.echo(f"\n{len(stories)} stories\n")
+
+
+@stories_group.command("view")
+@click.argument("story_id", type=int)
+@click.option("--comments/--no-comments", default=True, help="Show comments.")
+@click.option("-n", "--limit", default=10, show_default=True, help="Number of comments to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def stories_view(ctx, story_id, comments, limit, json_mode):
+    """View a story and its comments by ID."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        story = client.get_story(story_id)
+
+        if json_mode:
+            data = story.to_dict()
+            if comments:
+                cmts = client.get_comments(story_id, limit=limit)
+                data["comments"] = [c.to_dict() for c in cmts]
+            print_json(data)
+        else:
+            click.echo(f"\n  {story.title}")
+            if story.url:
+                click.echo(f"  {story.url}")
+            click.echo(
+                f"  {story.score} points by {story.by} | {story.age} | {story.descendants} comments"
+            )
+            click.echo()
+
+            if comments:
+                cmts = client.get_comments(story_id, limit=limit)
+                if cmts:
+                    click.echo("  Comments:\n")
+                    print_comments_list(cmts)

cli_web/hackernews/commands/user.py

@@ -0,0 +1,112 @@
+"""User command — view HN user profiles, favorites, and submissions."""
+
+from __future__ import annotations
+
+import click
+from cli_web.hackernews.core import auth
+from cli_web.hackernews.core.client import HackerNewsClient
+from cli_web.hackernews.utils.helpers import handle_errors, resolve_json_mode
+from cli_web.hackernews.utils.output import (
+    print_comments_list,
+    print_json,
+    print_stories_table,
+    print_user_profile,
+)
+
+
+@click.group("user")
+def user_group():
+    """View Hacker News user profiles."""
+
+
+@user_group.command("view")
+@click.argument("username")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def user_view(ctx, username, json_mode):
+    """View a user's profile by username."""
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        client = HackerNewsClient()
+        user = client.get_user(username)
+        if json_mode:
+            print_json(user.to_dict())
+        else:
+            click.echo(f"\nUser Profile: {username}\n")
+            print_user_profile(user)
+            click.echo()
+
+
+@user_group.command("favorites")
+@click.argument("username", required=False)
+@click.option("-n", "--limit", default=30, show_default=True, help="Number of items to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def user_favorites(ctx, username, limit, json_mode):
+    """View a user's favorite stories. (Requires auth)
+
+    If USERNAME is omitted, shows your own favorites.
+    """
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        if not username:
+            username = auth.get_username()
+        cookie = auth.get_user_cookie()
+        client = HackerNewsClient(user_cookie=cookie)
+        stories = client.get_favorites(username, limit=limit)
+        if json_mode:
+            print_json([s.to_dict() for s in stories])
+        else:
+            click.echo(f"\n{username}'s Favorites\n")
+            print_stories_table(stories)
+            click.echo(f"\n{len(stories)} stories\n")
+
+
+@user_group.command("submissions")
+@click.argument("username", required=False)
+@click.option("-n", "--limit", default=30, show_default=True, help="Number of items to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def user_submissions(ctx, username, limit, json_mode):
+    """View a user's submitted stories. (Requires auth)
+
+    If USERNAME is omitted, shows your own submissions.
+    """
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        if not username:
+            username = auth.get_username()
+        cookie = auth.get_user_cookie()
+        client = HackerNewsClient(user_cookie=cookie)
+        stories = client.get_submissions(username, limit=limit)
+        if json_mode:
+            print_json([s.to_dict() for s in stories])
+        else:
+            click.echo(f"\n{username}'s Submissions\n")
+            print_stories_table(stories)
+            click.echo(f"\n{len(stories)} stories\n")
+
+
+@user_group.command("threads")
+@click.argument("username", required=False)
+@click.option("-n", "--limit", default=20, show_default=True, help="Number of comments to show.")
+@click.option("--json", "json_mode", is_flag=True, help="Output as JSON.")
+@click.pass_context
+def user_threads(ctx, username, limit, json_mode):
+    """View comment replies to a user (your threads). (Requires auth)
+
+    If USERNAME is omitted, shows replies to your own comments.
+    """
+    json_mode = resolve_json_mode(json_mode)
+    with handle_errors(json_mode=json_mode):
+        if not username:
+            username = auth.get_username()
+        cookie = auth.get_user_cookie()
+        client = HackerNewsClient(user_cookie=cookie)
+        comments = client.get_threads(username, limit=limit)
+        if json_mode:
+            print_json([c.to_dict() for c in comments])
+        else:
+            click.echo(f"\n{username}'s Threads (replies)\n")
+            print_comments_list(comments)
+            click.echo(f"\n{len(comments)} comments\n")