From 8d540233258fc5f9e63eb62e9b75e4499713c31a Mon Sep 17 00:00:00 2001 From: shbernal Date: Fri, 30 Oct 2026 13:41:02 +0100 Subject: [PATCH 1/4] fix: make exit codes match the documented contract Network failures, rate limits and server errors now exit 8. Previously `read` and `user` reported every failure as not found (5), and `search` and `front` exited 1, so callers could not tell when to retry. `hn user` moves to the Firebase API because Algolia answers 500 for unknown users. An empty `hn front` exits 3, and `hn status --json` exits 8 when the API is down. --- AGENTS.md | 5 +- CHANGELOG.md | 7 +++ README.md | 6 +- internal/api/client.go | 119 +++++++++++++++++++----------------- internal/api/client_test.go | 81 +++++++++++++++++++++--- internal/cmd/root.go | 33 +++++----- 6 files changed, 162 insertions(+), 89 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1574ac9..a2066bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ Go CLI for Hacker News via the Algolia API. No auth required. - `cmd/hn/main.go` -- thin entrypoint, version embedding via ldflags - `internal/cmd/root.go` -- all CLI commands (cobra) -- `internal/api/client.go` -- HN Algolia API client +- `internal/api/client.go` -- HN Algolia and Firebase API client - `internal/output/format.go` -- compact plaintext and JSON formatters - `skills/hn/SKILL.md` -- agent skill definition @@ -28,4 +28,5 @@ Go CLI for Hacker News via the Algolia API. No auth required. ## API -HN Algolia API at `https://hn.algolia.com/api/v1/`. Free, no auth, no rate limits. +HN Algolia API at `https://hn.algolia.com/api/v1/`, and the official Firebase API +at `https://hacker-news.firebaseio.com/v0/` for what Algolia lacks. Free, no auth. diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e2b8d5..3a5158f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed +- Exit codes now match the docs. Network failures, rate limits and server + errors exit 8, missing items and users exit 5, and an empty `hn front` exits 3. +- `hn status --json` exits 8 when the API is down. +- `hn user` looks profiles up through the Firebase API, because Algolia answers + 500 for unknown users. + ## [0.2.1] — 2026-08-08 ### Fixed diff --git a/README.md b/README.md index e07e4dc..cf122f9 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Agent-friendly CLI for [Hacker News](https://news.ycombinator.com) via the [Algo - **Fast** — direct Algolia API, no scraping or HTML parsing - **Agent-friendly** — `--json` on every command, structured exit codes, stderr-only progress -- **Zero config** — no API keys, no auth, no rate limits +- **Zero config** — no API keys, no auth - **Single binary** — install via Homebrew, Scoop, or `go install`

@@ -113,7 +113,7 @@ npx skills add -g voska/hn-cli ## API -Uses the [HN Algolia API](https://hn.algolia.com/api/v1/) -- free, public, no authentication or API keys required. +Uses the [HN Algolia API](https://hn.algolia.com/api/v1/) for search and threads, and the [official Firebase API](https://github.com/HackerNews/API) for user profiles. Both are free and public, with no authentication or API keys required. ## Output Modes @@ -143,7 +143,7 @@ All commands support `--json`. | 1 | error | General error | | 3 | empty | No results found | | 5 | not_found | Invalid ID or username | -| 8 | retryable | Transient error, safe to retry | +| 8 | retryable | Network failure, rate limit or server error, safe to retry | ## Development diff --git a/internal/api/client.go b/internal/api/client.go index 5dc1595..4418851 100644 --- a/internal/api/client.go +++ b/internal/api/client.go @@ -2,6 +2,7 @@ package api import ( "encoding/json" + "errors" "fmt" "html" "net/http" @@ -11,28 +12,64 @@ import ( "time" ) -// BaseURL is the default HN Algolia API endpoint. -const BaseURL = "https://hn.algolia.com/api/v1" +const ( + // BaseURL is the default HN Algolia API endpoint. + BaseURL = "https://hn.algolia.com/api/v1" + // FirebaseURL is the default official HN API endpoint. + FirebaseURL = "https://hacker-news.firebaseio.com/v0" +) + +var ( + // ErrNotFound means the requested item or user does not exist. + ErrNotFound = errors.New("not found") + // ErrRetryable means a network failure, rate limit or server error. + ErrRetryable = errors.New("temporary failure") +) -// Client wraps an HTTP client and base URL for the HN Algolia API. +// Client wraps an HTTP client and base URLs for the HN APIs. type Client struct { - baseURL string - httpClient *http.Client + baseURL string + firebaseURL string + httpClient *http.Client } // NewClient returns a Client configured with the given base URL and HTTP client. func NewClient(baseURL string, httpClient *http.Client) *Client { return &Client{ - baseURL: baseURL, - httpClient: httpClient, + baseURL: baseURL, + firebaseURL: FirebaseURL, + httpClient: httpClient, } } -// DefaultClient returns a Client using the production API and a 15s timeout. +// DefaultClient returns a Client using the production APIs and a 15s timeout. func DefaultClient() *Client { return NewClient(BaseURL, &http.Client{Timeout: 15 * time.Second}) } +// getJSON fetches reqURL and decodes the response into v. +func (c *Client) getJSON(reqURL string, v any) error { + resp, err := c.httpClient.Get(reqURL) + if err != nil { + return fmt.Errorf("%w: %v", ErrRetryable, err) + } + defer resp.Body.Close() + + switch { + case resp.StatusCode == http.StatusNotFound: + return ErrNotFound + case resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= 500: + return fmt.Errorf("%w: api returned %d", ErrRetryable, resp.StatusCode) + case resp.StatusCode != http.StatusOK: + return fmt.Errorf("api returned %d", resp.StatusCode) + } + + if err := json.NewDecoder(resp.Body).Decode(v); err != nil { + return fmt.Errorf("decode failed: %w", err) + } + return nil +} + // SearchResult represents the Algolia search response. type SearchResult struct { Hits []Hit `json:"hits"` @@ -126,68 +163,38 @@ func (c *Client) BuildURL(opts SearchOptions) string { // Search queries the HN Algolia search API. func (c *Client) Search(opts SearchOptions) (*SearchResult, error) { - reqURL := c.BuildURL(opts) - resp, err := c.httpClient.Get(reqURL) - if err != nil { - return nil, fmt.Errorf("request failed: %w", err) - } - defer resp.Body.Close() - - if resp.StatusCode != http.StatusOK { - return nil, fmt.Errorf("api returned %d", resp.StatusCode) - } - var result SearchResult - if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { - return nil, fmt.Errorf("decode failed: %w", err) + if err := c.getJSON(c.BuildURL(opts), &result); err != nil { + return nil, err } return &result, nil } // GetItem fetches a single item (story/comment) with its children. func (c *Client) GetItem(id string) (*Item, error) { - reqURL := fmt.Sprintf("%s/items/%s", c.baseURL, id) - resp, err := c.httpClient.Get(reqURL) - if err != nil { - return nil, fmt.Errorf("request failed: %w", err) - } - defer resp.Body.Close() - - if resp.StatusCode == http.StatusNotFound { - return nil, fmt.Errorf("item %s not found", id) - } - if resp.StatusCode != http.StatusOK { - return nil, fmt.Errorf("api returned %d", resp.StatusCode) - } - var item Item - if err := json.NewDecoder(resp.Body).Decode(&item); err != nil { - return nil, fmt.Errorf("decode failed: %w", err) + if err := c.getJSON(fmt.Sprintf("%s/items/%s", c.baseURL, url.PathEscape(id)), &item); err != nil { + return nil, fmt.Errorf("item %s: %w", id, err) } return &item, nil } -// GetUser fetches a user profile. +// GetUser fetches a user profile. It uses the Firebase API because Algolia +// answers 500 for unknown users, which looks like an outage. func (c *Client) GetUser(username string) (*User, error) { - reqURL := fmt.Sprintf("%s/users/%s", c.baseURL, url.PathEscape(username)) - resp, err := c.httpClient.Get(reqURL) - if err != nil { - return nil, fmt.Errorf("request failed: %w", err) + var profile *struct { + ID string `json:"id"` + About string `json:"about"` + Karma int `json:"karma"` } - defer resp.Body.Close() - - if resp.StatusCode == http.StatusNotFound { - return nil, fmt.Errorf("user %q not found", username) - } - if resp.StatusCode != http.StatusOK { - return nil, fmt.Errorf("api returned %d", resp.StatusCode) + reqURL := fmt.Sprintf("%s/user/%s.json", c.firebaseURL, url.PathEscape(username)) + if err := c.getJSON(reqURL, &profile); err != nil { + return nil, fmt.Errorf("user %s: %w", username, err) } - - var user User - if err := json.NewDecoder(resp.Body).Decode(&user); err != nil { - return nil, fmt.Errorf("decode failed: %w", err) + if profile == nil { + return nil, fmt.Errorf("user %s: %w", username, ErrNotFound) } - return &user, nil + return &User{Username: profile.ID, About: profile.About, Karma: profile.Karma}, nil } // HealthCheck pings the API and returns latency. @@ -195,13 +202,13 @@ func (c *Client) HealthCheck() (time.Duration, error) { start := time.Now() resp, err := c.httpClient.Get(c.baseURL + "/search?query=test&hitsPerPage=0") if err != nil { - return 0, fmt.Errorf("api unreachable: %w", err) + return 0, fmt.Errorf("%w: %v", ErrRetryable, err) } defer resp.Body.Close() elapsed := time.Since(start) if resp.StatusCode != http.StatusOK { - return elapsed, fmt.Errorf("api returned %d", resp.StatusCode) + return elapsed, fmt.Errorf("%w: api returned %d", ErrRetryable, resp.StatusCode) } return elapsed, nil } diff --git a/internal/api/client_test.go b/internal/api/client_test.go index 9f3fc5d..f6f0e75 100644 --- a/internal/api/client_test.go +++ b/internal/api/client_test.go @@ -2,12 +2,20 @@ package api import ( "encoding/json" + "errors" "net/http" "net/http/httptest" "testing" "time" ) +// testClient points both APIs at srv. +func testClient(srv *httptest.Server) *Client { + c := NewClient(srv.URL, srv.Client()) + c.firebaseURL = srv.URL + return c +} + func TestBuildURL(t *testing.T) { c := NewClient("https://example.com/api/v1", http.DefaultClient) @@ -70,7 +78,7 @@ func TestSearch(t *testing.T) { })) defer srv.Close() - c := NewClient(srv.URL, srv.Client()) + c := testClient(srv) result, err := c.Search(SearchOptions{Query: "test"}) if err != nil { t.Fatalf("Search() error: %v", err) @@ -93,7 +101,7 @@ func TestGetItem(t *testing.T) { })) defer srv.Close() - c := NewClient(srv.URL, srv.Client()) + c := testClient(srv) item, err := c.GetItem("123") if err != nil { @@ -111,27 +119,80 @@ func TestGetItem(t *testing.T) { func TestGetUser(t *testing.T) { srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - if r.URL.Path == "/users/pg" { - json.NewEncoder(w).Encode(User{Username: "pg", Karma: 157316}) + if r.URL.Path == "/user/pg.json" { + w.Write([]byte(`{"id":"pg","karma":157316,"about":"Bug fixer."}`)) return } - w.WriteHeader(http.StatusNotFound) + w.Write([]byte("null")) })) defer srv.Close() - c := NewClient(srv.URL, srv.Client()) + c := testClient(srv) user, err := c.GetUser("pg") if err != nil { t.Fatalf("GetUser() error: %v", err) } - if user.Username != "pg" { - t.Errorf("expected username 'pg', got %q", user.Username) + if user.Username != "pg" || user.Karma != 157316 || user.About != "Bug fixer." { + t.Errorf("unexpected user: %+v", user) } _, err = c.GetUser("nonexistent_user_xyz") - if err == nil { - t.Error("expected error for missing user") + if !errors.Is(err, ErrNotFound) { + t.Errorf("expected ErrNotFound for missing user, got %v", err) + } +} + +func TestErrorClassification(t *testing.T) { + tests := []struct { + name string + status int + want error + }{ + {"not found", http.StatusNotFound, ErrNotFound}, + {"rate limited", http.StatusTooManyRequests, ErrRetryable}, + {"server error", http.StatusBadGateway, ErrRetryable}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(tt.status) + })) + defer srv.Close() + + c := testClient(srv) + if _, err := c.GetItem("1"); !errors.Is(err, tt.want) { + t.Errorf("GetItem() error = %v, want %v", err, tt.want) + } + }) + } +} + +func TestNetworkFailureIsRetryable(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {})) + url := srv.URL + srv.Close() + + c := NewClient(url, http.DefaultClient) + c.firebaseURL = url + if _, err := c.GetItem("1"); !errors.Is(err, ErrRetryable) { + t.Errorf("GetItem() error = %v, want ErrRetryable", err) + } + if _, err := c.Search(SearchOptions{Query: "go"}); !errors.Is(err, ErrRetryable) { + t.Errorf("Search() error = %v, want ErrRetryable", err) + } +} + +func TestClientErrorIsNotRetryable(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.WriteHeader(http.StatusBadRequest) + })) + defer srv.Close() + + c := testClient(srv) + if _, err := c.Search(SearchOptions{Query: "go"}); err == nil || errors.Is(err, ErrRetryable) { + t.Errorf("Search() error = %v, want a non-retryable error", err) } } diff --git a/internal/cmd/root.go b/internal/cmd/root.go index 284f3a1..ae0ddd0 100644 --- a/internal/cmd/root.go +++ b/internal/cmd/root.go @@ -1,6 +1,7 @@ package cmd import ( + "errors" "fmt" "os" "strings" @@ -25,16 +26,6 @@ type ErrNoResults struct{} func (e ErrNoResults) Error() string { return "no results" } -// ErrNotFound signals a missing resource (exit code 5). -type ErrNotFound struct{ msg string } - -func (e ErrNotFound) Error() string { return e.msg } - -// ErrRetryable signals a transient failure (exit code 8). -type ErrRetryable struct{ msg string } - -func (e ErrRetryable) Error() string { return e.msg } - func SetVersion(v, c, d string) { appVersion = v appCommit = c @@ -68,12 +59,12 @@ func Execute() error { // ExitCode maps sentinel errors to process exit codes. func ExitCode(err error) int { - switch err.(type) { - case ErrNoResults: + switch { + case errors.As(err, &ErrNoResults{}): return 3 - case ErrNotFound: + case errors.Is(err, api.ErrNotFound): return 5 - case ErrRetryable: + case errors.Is(err, api.ErrRetryable): return 8 default: return 1 @@ -168,6 +159,10 @@ var frontCmd = &cobra.Command{ return err } + if len(result.Hits) == 0 { + return ErrNoResults{} + } + if jsonOutput { return output.JSON(result) } @@ -192,7 +187,7 @@ var readCmd = &cobra.Command{ RunE: func(cmd *cobra.Command, args []string) error { item, err := client().GetItem(args[0]) if err != nil { - return ErrNotFound{msg: err.Error()} + return err } if jsonOutput { @@ -217,7 +212,7 @@ var userCmd = &cobra.Command{ RunE: func(cmd *cobra.Command, args []string) error { user, err := client().GetUser(args[0]) if err != nil { - return ErrNotFound{msg: err.Error()} + return err } if jsonOutput { @@ -237,9 +232,11 @@ var statusCmd = &cobra.Command{ latency, err := client().HealthCheck() if err != nil { if jsonOutput { - return output.JSON(map[string]any{"status": "error", "error": err.Error()}) + if jsonErr := output.JSON(map[string]any{"status": "error", "error": err.Error()}); jsonErr != nil { + return jsonErr + } } - return ErrRetryable{msg: fmt.Sprintf("HN API: DOWN (%v)", err)} + return fmt.Errorf("HN API: DOWN (%w)", err) } if jsonOutput { From 6c21b6ef0cf3be20fa6e6d3fd00f9b52fc521bef Mon Sep 17 00:00:00 2001 From: shbernal Date: Fri, 30 Oct 2026 13:42:33 +0100 Subject: [PATCH 2/4] feat: use site rank in front and read Algolia has no ranking: its front_page tag returns the right stories in another order, and threads come back oldest first. Take the order from the Firebase API and the details from Algolia, so `hn front` matches the site and `hn read` opens with the comments readers actually see. `hn front --feed` reaches the other lists. Job posts have no story tag on Algolia, so anything it lacks comes from single Firebase lookups. `hn read` now caps its output, because a large thread ran to 140 KB by default. It reports what it cuts, and shows comment IDs so a collapsed thread can be opened directly. --- CHANGELOG.md | 12 ++ README.md | 25 ++-- internal/api/client.go | 213 +++++++++++++++++++++++++++++++++ internal/api/client_test.go | 91 ++++++++++++++ internal/cmd/root.go | 49 ++++++-- internal/output/format.go | 87 +++++++++----- internal/output/format_test.go | 73 +++++++++++ skills/hn/SKILL.md | 20 +++- 8 files changed, 513 insertions(+), 57 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a5158f..49144ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added +- `hn front --feed` reads the `top`, `new`, `best`, `ask`, `show` and `job` lists. +- `hn read` flags `-n`, `--replies`, `--depth` and `--max-chars`, and comment IDs + in its output. `hn read COMMENT_ID` opens a collapsed thread. + +### Changed +- `hn read` caps its output by default, and says what it leaves out. `--expand` + shows everything. + ### Fixed +- `hn front` lists stories in site rank order. Algolia's `front_page` tag has + the right stories in another order. +- `hn read` lists comments in site rank order, not oldest first. - Exit codes now match the docs. Network failures, rate limits and server errors exit 8, missing items and users exit 5, and an empty `hn front` exits 3. - `hn status --json` exits 8 when the API is down. diff --git a/README.md b/README.md index cf122f9..ecab229 100644 --- a/README.md +++ b/README.md @@ -41,8 +41,8 @@ $ hn front -n 3 3. [145pts 53c] The death of microservices @mfiguiere 6h ago https://example.com/microservices -$ hn read 43163011 --json | jq '.comments | length' -963 +$ hn read 43163011 --json | jq '.children | length' +412 ``` Run `hn --help` for the full command tree. @@ -87,13 +87,22 @@ hn search "Go vs Rust" --comments # Recent stories sorted by date hn search "WASM" --sort date --after 2026-01-01 -# Current front page +# Current front page, in site rank order hn front -# Read a story with comments (3 levels deep) +# Other feeds: new, best, ask, show, job +hn front --feed show -n 10 + +# Read a story with its top comments hn read 43163011 -# Read with all comments expanded +# Open a collapsed thread by comment ID +hn read 43163150 + +# Fewer comments, shorter +hn read 43163011 -n 5 --replies 1 --max-chars 300 + +# Read every comment in full hn read 43163011 --expand # User profile @@ -113,7 +122,7 @@ npx skills add -g voska/hn-cli ## API -Uses the [HN Algolia API](https://hn.algolia.com/api/v1/) for search and threads, and the [official Firebase API](https://github.com/HackerNews/API) for user profiles. Both are free and public, with no authentication or API keys required. +Uses the [HN Algolia API](https://hn.algolia.com/api/v1/) for search and threads, and the [official Firebase API](https://github.com/HackerNews/API) for site ranking and user profiles. Both are free and public, with no authentication or API keys required. ## Output Modes @@ -127,8 +136,8 @@ Uses the [HN Algolia API](https://hn.algolia.com/api/v1/) for search and threads | Command | Alias | Description | |---------|-------|-------------| | `search ` | `s` | Search stories or comments | -| `front` | `f` | Current front page stories | -| `read ` | `r` | Story with threaded comments | +| `front` | `f` | Stories in site rank order, from any feed | +| `read ` | `r` | Story or comment with its top comments | | `user ` | `u` | User profile and karma | | `status` | | API health check with latency | | `version` | | Version, commit, build date | diff --git a/internal/api/client.go b/internal/api/client.go index 4418851..73e93b0 100644 --- a/internal/api/client.go +++ b/internal/api/client.go @@ -7,8 +7,10 @@ import ( "html" "net/http" "net/url" + "sort" "strconv" "strings" + "sync" "time" ) @@ -19,6 +21,23 @@ const ( FirebaseURL = "https://hacker-news.firebaseio.com/v0" ) +const ( + // feedChunk is how many story IDs fit in one Algolia tag filter. + feedChunk = 100 + // maxConcurrent caps parallel Firebase requests. + maxConcurrent = 10 +) + +// feedLists maps feed names to Firebase story lists. +var feedLists = map[string]string{ + "top": "topstories", + "new": "newstories", + "best": "beststories", + "ask": "askstories", + "show": "showstories", + "job": "jobstories", +} + var ( // ErrNotFound means the requested item or user does not exist. ErrNotFound = errors.New("not found") @@ -119,6 +138,33 @@ type User struct { Karma int `json:"karma"` } +// firebaseItem is an item from the Firebase API. +type firebaseItem struct { + ID int `json:"id"` + By string `json:"by"` + Title string `json:"title"` + URL string `json:"url"` + Score int `json:"score"` + Descendants int `json:"descendants"` + Time int64 `json:"time"` + Dead bool `json:"dead"` + Deleted bool `json:"deleted"` + Kids []int `json:"kids"` +} + +func (f firebaseItem) hit() Hit { + return Hit{ + ObjectID: strconv.Itoa(f.ID), + Title: f.Title, + URL: f.URL, + Author: f.By, + Points: f.Score, + NumComments: f.Descendants, + CreatedAt: time.Unix(f.Time, 0).UTC().Format(time.RFC3339), + CreatedAtI: f.Time, + } +} + // SearchOptions configures a search request. type SearchOptions struct { Query string @@ -170,6 +216,173 @@ func (c *Client) Search(opts SearchOptions) (*SearchResult, error) { return &result, nil } +// FeedNames returns the valid feed names, sorted. +func FeedNames() []string { + names := make([]string, 0, len(feedLists)) + for name := range feedLists { + names = append(names, name) + } + sort.Strings(names) + return names +} + +// Feed returns the first n stories of a feed in site rank order. The order +// comes from Firebase and the details from Algolia, with single Firebase +// lookups for what Algolia lacks: job posts and stories not indexed yet. +func (c *Client) Feed(feed string, n int) (*SearchResult, error) { + list, ok := feedLists[feed] + if !ok { + return nil, fmt.Errorf("unknown feed %q (use %s)", feed, strings.Join(FeedNames(), ", ")) + } + + var ids []int + if err := c.getJSON(fmt.Sprintf("%s/%s.json", c.firebaseURL, list), &ids); err != nil { + return nil, fmt.Errorf("feed %s: %w", feed, err) + } + if n > 0 && n < len(ids) { + ids = ids[:n] + } + + found := make(map[string]Hit, len(ids)) + for start := 0; start < len(ids); start += feedChunk { + chunk := ids[start:min(start+feedChunk, len(ids))] + tags := make([]string, len(chunk)) + for i, id := range chunk { + tags[i] = fmt.Sprintf("story_%d", id) + } + result, err := c.Search(SearchOptions{ + Tags: "(story,job),(" + strings.Join(tags, ",") + ")", + NumResults: len(chunk), + }) + if err != nil { + return nil, err + } + for _, hit := range result.Hits { + found[hit.ObjectID] = hit + } + } + + if err := c.fillMissing(ids, found); err != nil { + return nil, err + } + + hits := make([]Hit, 0, len(ids)) + for _, id := range ids { + if hit, ok := found[strconv.Itoa(id)]; ok { + hits = append(hits, hit) + } + } + return &SearchResult{Hits: hits, NbHits: len(hits), HitsPerPage: len(ids)}, nil +} + +// fillMissing adds to found the ids it lacks, looked up on Firebase. Dead and +// deleted items stay out. +func (c *Client) fillMissing(ids []int, found map[string]Hit) error { + var ( + wg sync.WaitGroup + mu sync.Mutex + firstErr error + slots = make(chan struct{}, maxConcurrent) + ) + for _, id := range ids { + if _, ok := found[strconv.Itoa(id)]; ok { + continue + } + wg.Add(1) + slots <- struct{}{} + go func() { + defer wg.Done() + defer func() { <-slots }() + + fb, err := c.firebaseItem(id) + mu.Lock() + defer mu.Unlock() + switch { + case err != nil: + if firstErr == nil { + firstErr = err + } + case fb != nil && !fb.Dead && !fb.Deleted: + found[strconv.Itoa(id)] = fb.hit() + } + }() + } + wg.Wait() + return firstErr +} + +// firebaseItem fetches one item from the Firebase API. It returns nil when the +// item does not exist. +func (c *Client) firebaseItem(id int) (*firebaseItem, error) { + var fb *firebaseItem + if err := c.getJSON(fmt.Sprintf("%s/item/%d.json", c.firebaseURL, id), &fb); err != nil { + return nil, fmt.Errorf("item %d: %w", id, err) + } + return fb, nil +} + +// RankComments sorts item's comments into site rank order, and the replies of +// the first n comments too. Algolia returns comments oldest first, and only +// Firebase knows the ranking. Deeper replies stay oldest first. +func (c *Client) RankComments(item *Item, n int) error { + if err := c.rankChildren(item); err != nil { + return err + } + + children := item.Children + if n <= 0 { + return nil + } + if n < len(children) { + children = children[:n] + } + + var ( + wg sync.WaitGroup + slots = make(chan struct{}, maxConcurrent) + ) + for i := range children { + if len(children[i].Children) < 2 { + continue + } + wg.Add(1) + slots <- struct{}{} + go func() { + defer wg.Done() + defer func() { <-slots }() + // Replies are only reordered, so a failed lookup costs nothing. + _ = c.rankChildren(&children[i]) + }() + } + wg.Wait() + return nil +} + +func (c *Client) rankChildren(item *Item) error { + fb, err := c.firebaseItem(item.ID) + if err != nil { + return err + } + if fb == nil { + return fmt.Errorf("item %d: %w", item.ID, ErrNotFound) + } + + rank := make(map[int]int, len(fb.Kids)) + for i, id := range fb.Kids { + rank[id] = i + } + position := func(id int) int { + if r, ok := rank[id]; ok { + return r + } + return len(fb.Kids) + } + sort.SliceStable(item.Children, func(i, j int) bool { + return position(item.Children[i].ID) < position(item.Children[j].ID) + }) + return nil +} + // GetItem fetches a single item (story/comment) with its children. func (c *Client) GetItem(id string) (*Item, error) { var item Item diff --git a/internal/api/client_test.go b/internal/api/client_test.go index f6f0e75..d1eb309 100644 --- a/internal/api/client_test.go +++ b/internal/api/client_test.go @@ -5,6 +5,7 @@ import ( "errors" "net/http" "net/http/httptest" + "slices" "testing" "time" ) @@ -196,6 +197,96 @@ func TestClientErrorIsNotRetryable(t *testing.T) { } } +func TestFeed(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch r.URL.Path { + case "/topstories.json": + w.Write([]byte("[30,10,20,40,50]")) + case "/search": + if got := r.URL.Query().Get("tags"); got != "(story,job),(story_30,story_10,story_20,story_40)" { + t.Errorf("tags = %q", got) + } + json.NewEncoder(w).Encode(SearchResult{Hits: []Hit{ + {ObjectID: "10", Title: "ten"}, + {ObjectID: "30", Title: "thirty"}, + }}) + case "/item/20.json": + w.Write([]byte(`{"id":20,"type":"job","title":"twenty","by":"yc","score":1,"time":1700000000}`)) + case "/item/40.json": + w.Write([]byte(`{"id":40,"dead":true,"title":"forty"}`)) + default: + t.Errorf("unexpected request %s", r.URL.Path) + } + })) + defer srv.Close() + + c := testClient(srv) + result, err := c.Feed("top", 4) + if err != nil { + t.Fatalf("Feed() error: %v", err) + } + + var titles []string + for _, hit := range result.Hits { + titles = append(titles, hit.Title) + } + if want := []string{"thirty", "ten", "twenty"}; !slices.Equal(titles, want) { + t.Errorf("titles = %v, want %v", titles, want) + } + if result.Hits[2].CreatedAt != "2023-11-14T22:13:20Z" { + t.Errorf("CreatedAt = %q", result.Hits[2].CreatedAt) + } +} + +func TestFeedUnknown(t *testing.T) { + c := NewClient("", http.DefaultClient) + if _, err := c.Feed("nope", 1); err == nil { + t.Error("expected error for unknown feed") + } +} + +func TestRankComments(t *testing.T) { + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch r.URL.Path { + case "/item/1.json": + w.Write([]byte(`{"id":1,"kids":[4,2]}`)) + case "/item/4.json": + w.Write([]byte(`{"id":4,"kids":[6,5]}`)) + default: + t.Errorf("unexpected request %s", r.URL.Path) + } + })) + defer srv.Close() + + item := &Item{ID: 1, Children: []Item{ + {ID: 2, Children: []Item{{ID: 8}, {ID: 7}}}, + {ID: 3}, + {ID: 4, Children: []Item{{ID: 5}, {ID: 6}}}, + }} + + c := testClient(srv) + if err := c.RankComments(item, 1); err != nil { + t.Fatalf("RankComments() error: %v", err) + } + + ids := func(items []Item) []int { + var out []int + for _, it := range items { + out = append(out, it.ID) + } + return out + } + if got, want := ids(item.Children), []int{4, 2, 3}; !slices.Equal(got, want) { + t.Errorf("comments = %v, want %v", got, want) + } + if got, want := ids(item.Children[0].Children), []int{6, 5}; !slices.Equal(got, want) { + t.Errorf("ranked replies = %v, want %v", got, want) + } + if got, want := ids(item.Children[1].Children), []int{8, 7}; !slices.Equal(got, want) { + t.Errorf("replies past n = %v, want %v", got, want) + } +} + func TestCleanHTML(t *testing.T) { tests := []struct { name string diff --git a/internal/cmd/root.go b/internal/cmd/root.go index ae0ddd0..be6976b 100644 --- a/internal/cmd/root.go +++ b/internal/cmd/root.go @@ -144,17 +144,17 @@ func init() { // --- front --- -var frontNum int +var ( + frontNum int + frontFeed string +) var frontCmd = &cobra.Command{ Use: "front", Aliases: []string{"f"}, - Short: "Current front page stories", + Short: "Stories in site rank order", RunE: func(cmd *cobra.Command, args []string) error { - result, err := client().Search(api.SearchOptions{ - Tags: "front_page", - NumResults: frontNum, - }) + result, err := client().Feed(frontFeed, frontNum) if err != nil { return err } @@ -166,40 +166,65 @@ var frontCmd = &cobra.Command{ if jsonOutput { return output.JSON(result) } - output.FormatFrontPage(os.Stdout, result) + output.FormatFeed(os.Stdout, result, frontFeed) return nil }, } func init() { frontCmd.Flags().IntVarP(&frontNum, "num", "n", 30, "Number of stories") + frontCmd.Flags().StringVar(&frontFeed, "feed", "top", "Feed: "+strings.Join(api.FeedNames(), ", ")) } // --- read --- -var readExpand bool +var ( + readNum int + readReplies int + readDepth int + readMaxChars int + readExpand bool +) var readCmd = &cobra.Command{ Use: "read ID", Aliases: []string{"r"}, - Short: "Read a story with comments", - Args: cobra.ExactArgs(1), + Short: "Read a story or comment with its top comments", + Long: `Read a story or comment with its comments in site rank order. The output is +capped to fit an agent's context, and names what it leaves out. Comment IDs +open a collapsed thread: hn read COMMENT_ID. + +--json returns the whole tree in rank order and ignores the caps.`, + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { item, err := client().GetItem(args[0]) if err != nil { return err } + opts := output.ReadOptions{Num: readNum, Replies: readReplies, Depth: readDepth, MaxChars: readMaxChars} + if readExpand { + opts = output.ReadOptions{Replies: -1, Depth: -1} + } + + if err := client().RankComments(item, opts.Num); err != nil { + fmt.Fprintf(os.Stderr, "warning: comments are oldest first: %v\n", err) + } + if jsonOutput { return output.JSON(item) } - output.FormatItem(os.Stdout, item, readExpand) + output.FormatItem(os.Stdout, item, opts) return nil }, } func init() { - readCmd.Flags().BoolVar(&readExpand, "expand", false, "Show all comments expanded") + readCmd.Flags().IntVarP(&readNum, "num", "n", 20, "Top comments to show, 0 for all") + readCmd.Flags().IntVar(&readReplies, "replies", 3, "Replies to show per comment") + readCmd.Flags().IntVar(&readDepth, "depth", 1, "Levels of replies to show") + readCmd.Flags().IntVar(&readMaxChars, "max-chars", 800, "Characters per comment, 0 for no cap") + readCmd.Flags().BoolVar(&readExpand, "expand", false, "Show every comment in full") } // --- user --- diff --git a/internal/output/format.go b/internal/output/format.go index 3d624ff..8e38f33 100644 --- a/internal/output/format.go +++ b/internal/output/format.go @@ -39,10 +39,7 @@ func formatStory(w io.Writer, n int, hit api.Hit) { func formatComment(w io.Writer, n int, hit api.Hit) { ago := timeAgo(hit.CreatedAt) - text := api.CleanHTML(hit.CommentText) - if len(text) > 200 { - text = text[:200] + "..." - } + text := truncate(api.CleanHTML(hit.CommentText), 200) text = strings.ReplaceAll(text, "\n", " ") storyTitle := hit.StoryTitle @@ -54,28 +51,42 @@ func formatComment(w io.Writer, n int, hit api.Hit) { fmt.Fprintf(w, " HN: https://news.ycombinator.com/item?id=%s\n", hit.ObjectID) } -// FormatFrontPage prints front page stories in compact plaintext. -func FormatFrontPage(w io.Writer, result *api.SearchResult) { +// FormatFeed prints a story feed in compact plaintext. +func FormatFeed(w io.Writer, result *api.SearchResult, feed string) { if len(result.Hits) == 0 { - fmt.Fprintln(w, "No stories on front page.") + fmt.Fprintln(w, "No stories.") return } - fmt.Fprintf(w, "Front page (%d stories):\n", len(result.Hits)) + title := "Front page" + if feed != "top" { + title = "Feed " + feed + } + fmt.Fprintf(w, "%s (%d stories):\n", title, len(result.Hits)) for i, hit := range result.Hits { formatStory(w, i+1, hit) } } -// FormatItem prints a story with its comments. -func FormatItem(w io.Writer, item *api.Item, expand bool) { +// ReadOptions caps the comments FormatItem prints. +type ReadOptions struct { + Num int // top comments, 0 for all + Replies int // replies per comment, negative for all + Depth int // levels of replies, negative for all + MaxChars int // characters per comment, 0 for no cap +} + +// FormatItem prints a story or comment with its comments. +func FormatItem(w io.Writer, item *api.Item, opts ReadOptions) { pts := 0 if item.Points != nil { pts = *item.Points } ago := timeAgo(item.CreatedAt) - fmt.Fprintf(w, "%s\n", item.Title) + if item.Title != "" { + fmt.Fprintf(w, "%s\n", item.Title) + } fmt.Fprintf(w, "@%s %dpts %s\n", item.Author, pts, ago) if item.URL != "" { fmt.Fprintf(w, "%s\n", item.URL) @@ -93,11 +104,11 @@ func FormatItem(w io.Writer, item *api.Item, expand bool) { } fmt.Fprintf(w, "\n--- %d comments ---\n", commentCount) - if expand { - printComments(w, item.Children, 0, -1) - } else { - printComments(w, item.Children, 0, 3) + limit := opts.Num + if limit <= 0 { + limit = -1 } + printComments(w, item.Children, 0, limit, opts) } // FormatUser prints user profile in compact plaintext. @@ -116,34 +127,48 @@ func JSON(v any) error { return enc.Encode(v) } -func printComments(w io.Writer, children []api.Item, depth int, maxDepth int) { - if maxDepth >= 0 && depth > maxDepth { - return - } - +func printComments(w io.Writer, children []api.Item, depth, limit int, opts ReadOptions) { indent := strings.Repeat(" ", depth) - for _, c := range children { + + shown := 0 + for i, c := range children { if c.Author == "" && c.Text == "" { continue } + if limit >= 0 && shown == limit { + noun := "replies" + if depth == 0 { + noun = "comments" + } + fmt.Fprintf(w, "%s[%d more %s]\n", indent, countComments(children[i:]), noun) + return + } + shown++ + ago := timeAgo(c.CreatedAt) - fmt.Fprintf(w, "%s@%s %s\n", indent, c.Author, ago) - text := api.CleanHTML(c.Text) + fmt.Fprintf(w, "%s@%s %s #%d\n", indent, c.Author, ago, c.ID) + text := truncate(api.CleanHTML(c.Text), opts.MaxChars) for _, line := range strings.Split(text, "\n") { fmt.Fprintf(w, "%s %s\n", indent, line) } - if len(c.Children) > 0 { - if maxDepth >= 0 && depth+1 > maxDepth { - collapsed := countComments(c.Children) - if collapsed > 0 { - fmt.Fprintf(w, "%s [%d more replies]\n", indent, collapsed) - } - } else { - printComments(w, c.Children, depth+1, maxDepth) + if opts.Depth >= 0 && depth >= opts.Depth { + if collapsed := countComments(c.Children); collapsed > 0 { + fmt.Fprintf(w, "%s [%d more replies]\n", indent, collapsed) } + continue } + printComments(w, c.Children, depth+1, opts.Replies, opts) + } +} + +// truncate caps s at maxChars characters and says how many it dropped. +func truncate(s string, maxChars int) string { + runes := []rune(s) + if maxChars <= 0 || len(runes) <= maxChars { + return s } + return fmt.Sprintf("%s... [+%d chars]", string(runes[:maxChars]), len(runes)-maxChars) } func countComments(children []api.Item) int { diff --git a/internal/output/format_test.go b/internal/output/format_test.go index 4998f28..12f6356 100644 --- a/internal/output/format_test.go +++ b/internal/output/format_test.go @@ -48,6 +48,79 @@ func TestFormatSearchResults(t *testing.T) { } } +func TestFormatItemCaps(t *testing.T) { + story := &api.Item{ + ID: 1, + Title: "Story", + Author: "pg", + Children: []api.Item{ + {ID: 2, Author: "a", Text: "first", Children: []api.Item{ + {ID: 3, Author: "b", Text: "reply one", Children: []api.Item{{ID: 4, Author: "c", Text: "deep"}}}, + {ID: 5, Author: "d", Text: "reply two"}, + {ID: 6, Author: "e", Text: "reply three"}, + }}, + {ID: 7, Author: "f", Text: strings.Repeat("é", 20)}, + {ID: 8, Author: "g", Text: "hidden", Children: []api.Item{{ID: 9, Author: "h", Text: "hidden too"}}}, + }, + } + + var buf strings.Builder + FormatItem(&buf, story, ReadOptions{Num: 2, Replies: 1, Depth: 1, MaxChars: 10}) + out := buf.String() + + for _, want := range []string{ + "--- 8 comments ---", + "@a ", + "#2\n", + "reply one", + "[1 more replies]", + "[2 more replies]", + strings.Repeat("é", 10) + "... [+10 chars]", + "[2 more comments]", + } { + if !strings.Contains(out, want) { + t.Errorf("expected %q in output:\n%s", want, out) + } + } + for _, unwanted := range []string{"deep", "reply two", "hidden"} { + if strings.Contains(out, unwanted) { + t.Errorf("did not expect %q in output:\n%s", unwanted, out) + } + } +} + +func TestFormatItemExpanded(t *testing.T) { + story := &api.Item{ID: 1, Title: "Story", Children: []api.Item{ + {ID: 2, Author: "a", Text: "one", Children: []api.Item{ + {ID: 3, Author: "b", Text: "two", Children: []api.Item{{ID: 4, Author: "c", Text: "three"}}}, + }}, + }} + + var buf strings.Builder + FormatItem(&buf, story, ReadOptions{Replies: -1, Depth: -1}) + out := buf.String() + + if !strings.Contains(out, "three") || strings.Contains(out, "more") { + t.Errorf("expected the full thread, got:\n%s", out) + } +} + +func TestFormatFeed(t *testing.T) { + result := &api.SearchResult{Hits: []api.Hit{{ObjectID: "1", Title: "Launch"}}} + + var buf strings.Builder + FormatFeed(&buf, result, "top") + if !strings.Contains(buf.String(), "Front page (1 stories):") { + t.Errorf("unexpected header: %q", buf.String()) + } + + buf.Reset() + FormatFeed(&buf, result, "show") + if !strings.Contains(buf.String(), "Feed show (1 stories):") { + t.Errorf("unexpected header: %q", buf.String()) + } +} + func TestFormatUser(t *testing.T) { user := &api.User{ Username: "pg", diff --git a/skills/hn/SKILL.md b/skills/hn/SKILL.md index 24f2d27..edef594 100644 --- a/skills/hn/SKILL.md +++ b/skills/hn/SKILL.md @@ -22,11 +22,15 @@ hn search "query" -n 10 # Limit results hn search "query" --after 2026-01-01 # Only results after date hn search "query" --min-points 100 # Minimum points filter -hn front # Current front page stories +hn front # Front page in site rank order hn front -n 10 # Fewer results +hn front --feed show # top, new, best, ask, show or job -hn read ID # Read story + top comments -hn read ID --expand # All comments expanded +hn read ID # Story + top comments, capped +hn read ID -n 5 --replies 1 # Fewer comments +hn read ID --max-chars 300 # Shorter comments +hn read COMMENT_ID # Open a collapsed thread +hn read ID --expand # Every comment in full hn user USERNAME # User profile and karma @@ -41,7 +45,9 @@ Aliases: `hn s` = `hn search`, `hn f` = `hn front`, `hn r` = `hn read`, `hn u` = 1. Search or browse front page: `hn search "topic" -n 5` or `hn front` 2. Note the item ID from the HN URL in results 3. Read the full story + comments: `hn read ID` -4. Expand all comments if needed: `hn read ID --expand` +4. Open a thread with `hn read COMMENT_ID`, using the `#ID` on any comment +5. Use `--expand` only when you need the whole thread: a big one costs tens of + thousands of tokens ## Output Format @@ -59,8 +65,10 @@ to files -- never use `--json` in LLM context. ### Read output -Full story title, metadata, URL, body text, and threaded comments with author -and timestamps. Top 3 levels by default, `--expand` for all. +Full story title, metadata, URL, body text, and comments in site rank order +with author, timestamp and `#ID`. By default 20 comments, 3 replies each, one +level of replies and 800 characters per comment. Cuts show as `[N more replies]`, +`[N more comments]` and `[+N chars]`. ### User output From 83f79931fc231d9b72e03efb97f41fccd1a838de Mon Sep 17 00:00:00 2001 From: Matt Voska <3444419+voska@users.noreply.github.com> Date: Wed, 18 Nov 2026 20:28:00 -0300 Subject: [PATCH 3/4] fix: build the missing-ID list before starting lookups --- internal/api/client.go | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/internal/api/client.go b/internal/api/client.go index c3f543e..a8e548f 100644 --- a/internal/api/client.go +++ b/internal/api/client.go @@ -292,16 +292,20 @@ func (c *Client) Feed(feed string, n int) (*SearchResult, error) { // fillMissing adds to found the ids it lacks, looked up on Firebase. Dead and // deleted items stay out. func (c *Client) fillMissing(ids []int, found map[string]Hit) error { + var missing []int + for _, id := range ids { + if _, ok := found[strconv.Itoa(id)]; !ok { + missing = append(missing, id) + } + } + var ( wg sync.WaitGroup mu sync.Mutex firstErr error slots = make(chan struct{}, maxConcurrent) ) - for _, id := range ids { - if _, ok := found[strconv.Itoa(id)]; ok { - continue - } + for _, id := range missing { wg.Add(1) slots <- struct{}{} go func() { From 7abeaf71af888f29209e43d7edfdd98336c37e0d Mon Sep 17 00:00:00 2001 From: Matt Voska <3444419+voska@users.noreply.github.com> Date: Wed, 18 Nov 2026 20:28:08 -0300 Subject: [PATCH 4/4] docs: correct the --json rank-order claim in read help --- internal/cmd/root.go | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/internal/cmd/root.go b/internal/cmd/root.go index 730794e..0e55689 100644 --- a/internal/cmd/root.go +++ b/internal/cmd/root.go @@ -226,7 +226,8 @@ var readCmd = &cobra.Command{ capped to fit an agent's context, and names what it leaves out. Comment IDs open a collapsed thread: hn read COMMENT_ID. ---json returns the whole tree in rank order and ignores the caps.`, +--json returns the whole tree and ignores the caps. Only top-level comments +and the direct replies of the first -n comments are in rank order.`, Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { item, err := client().GetItem(args[0])