feat(tools): reddit + hackernews tools (T-0020, T-0021)

Author: jadb

docs/stories/054-tool-reddit.md

@@ -0,0 +1,35 @@
+# 054 - Tool: reddit
+
+**Persona:** [CLI User](../personas/cli-user.md),
+[AI Coding Assistant](../personas/ai-coding-assistant.md)
+
+## Goal
+
+Search Reddit for posts matching a query and extract structured metadata
+(title, subreddit, score, comment count, URL, snippet) for each result.
+
+## Stories
+
+- As a CLI user, I run `ibr tool reddit --param query=rust async` to retrieve
+  a list of Reddit posts with title, subreddit, score, comment_count, url, and snippet.
+- As a CLI user, I pass `--param subreddit=rust` to scope results to a single subreddit.
+- As a CLI user, I pass `--param sort=hot` to sort by hot posts.
+- As a CLI user, I pass `--param max_results=10` to control how many results are returned.
+- As a CLI user, omitting `query` produces a non-zero exit with a clear error message.
+
+## Acceptance Criteria
+
+- Navigates to `https://www.reddit.com/search/?q={{query}}&sort={{sort}}` by default.
+- When `subreddit` is set, navigates to
+  `https://www.reddit.com/r/{{subreddit}}/search/?q={{query}}&sort={{sort}}` instead.
+- Extracts up to `max_results` (default 5) posts per run.
+- Each extracted item contains: `title`, `subreddit`, `score`, `comment_count`,
+  `url`, `snippet`.
+- `sort` defaults to `relevance`; accepted values: relevance, hot, new, top.
+- Missing required param `query` → non-zero exit with "Missing required param: query".
+- Exit code 0 on successful extraction; stdout contains "Task execution completed".
+
+## E2E Coverage
+
+- `test/e2e/cli-tool-vcr.test.js` — VCR: exits 0, no config errors; required param
+  validation.

docs/stories/055-tool-hackernews.md

@@ -0,0 +1,34 @@
+# 055 - Tool: hackernews
+
+**Persona:** [CLI User](../personas/cli-user.md),
+[AI Coding Assistant](../personas/ai-coding-assistant.md)
+
+## Goal
+
+Search Hacker News via Algolia and extract structured metadata (title, points,
+comment count, author, URL, HN URL) for each result.
+
+## Stories
+
+- As a CLI user, I run `ibr tool hackernews --param query=rust async` to retrieve
+  a list of HN posts with title, points, comment_count, author, url, and hn_url.
+- As a CLI user, I pass `--param type=job` to filter to job posts.
+- As a CLI user, I pass `--param sort=date` to sort by most recent.
+- As a CLI user, I pass `--param max_results=5` to control how many results are returned.
+- As a CLI user, omitting `query` produces a non-zero exit with a clear error message.
+
+## Acceptance Criteria
+
+- Navigates to `https://hn.algolia.com/?q={{query}}&type={{type}}&sort=by{{sort}}`.
+- Extracts up to `max_results` (default 10) items per run.
+- Each extracted item contains: `title`, `points`, `comment_count`, `author`,
+  `url`, `hn_url`.
+- `type` defaults to `story`; accepted values: story, comment, job, poll.
+- `sort` defaults to `popularity`; accepted values: date, popularity.
+- Missing required param `query` → non-zero exit with "Missing required param: query".
+- Exit code 0 on successful extraction; stdout contains "Task execution completed".
+
+## E2E Coverage
+
+- `test/e2e/cli-tool-vcr.test.js` — VCR: exits 0, no config errors; required param
+  validation.

test/e2e/cassettes/tool-hackernews.json

@@ -0,0 +1,4 @@
+[
+  "{\"url\":\"{SERVER_URL}/tool-results.html\",\"instructions\":[{\"name\":\"extract\",\"prompt\":\"extract HN stories with title, points, comment_count, author, url, and hn_url\"}]}",
+  "[{\"title\":\"Rust async runtimes compared\",\"points\":342,\"comment_count\":94,\"author\":\"tptacek\",\"url\":\"https://example.com/rust-async\",\"hn_url\":\"https://news.ycombinator.com/item?id=12345678\"}]"
+]

test/e2e/cassettes/tool-reddit.json

@@ -0,0 +1,4 @@
+[
+  "{\"url\":\"{SERVER_URL}/tool-results.html\",\"instructions\":[{\"name\":\"extract\",\"prompt\":\"extract Reddit posts with title, subreddit, score, comment_count, url, and snippet\"}]}",
+  "[{\"title\":\"Why I switched to Rust for async services\",\"subreddit\":\"rust\",\"score\":1240,\"comment_count\":87,\"url\":\"https://example.com/rust-async\",\"snippet\":\"After struggling with Go concurrency...\"}]"
+]

tools/hackernews.yaml

@@ -0,0 +1,20 @@
+name: hackernews
+description: Search Hacker News via Algolia and extract story title, points, comment count, author, URL, and HN URL
+params:
+  - name: query
+    description: Search terms
+    required: true
+  - name: type
+    description: Item type — story, comment, job, or poll
+    default: "story"
+  - name: sort
+    description: Sort order — date or popularity
+    default: "popularity"
+  - name: max_results
+    description: Maximum number of results to extract
+    default: "10"
+url: "https://hn.algolia.com/?q={{query}}&type={{type}}&sort=by{{sort}}"
+instructions:
+  - wait for search results to load
+  - extract the top {{max_results}} results; for each result include title, points,
+    comment_count, author, url, and hn_url

tools/reddit.yaml

@@ -0,0 +1,22 @@
+name: reddit
+description: Search Reddit and extract post title, subreddit, score, comment count, URL, and snippet
+params:
+  - name: query
+    description: Search terms
+    required: true
+  - name: subreddit
+    description: Scope search to a specific subreddit (leave empty for site-wide)
+    default: ""
+  - name: sort
+    description: Sort order — relevance, hot, new, or top
+    default: "relevance"
+  - name: max_results
+    description: Maximum number of results to extract
+    default: "5"
+url: "https://www.reddit.com/search/?q={{query}}&sort={{sort}}"
+instructions:
+  - if subreddit param is non-empty, navigate to
+    https://www.reddit.com/r/{{subreddit}}/search/?q={{query}}&sort={{sort}} instead
+  - wait for search results to load
+  - extract the top {{max_results}} results; for each result include title, subreddit,
+    score, comment_count, url, and snippet