Since 30 June 2026 every logged-out request to old.reddit.com, HTML, .json,
and .rss alike, lands on /login/?reason=lor2, so every oc reddit verb rendered
an empty login page. The www.reddit.com .json views closed a month earlier and
answer 403 to anything without an OAuth token, whatever the User-Agent or TLS
fingerprint, so they are not a way back in either.
The Atom feeds on www.reddit.com still answer without a login, and the feed
converter already turns one into a page: a subreddit renders in about 480
tokens from a 21,500 token payload, a thread with 22 comments in about 1,000.
Every verb now points at a feed, and new <name> and top <name> join them,
since the feeds offer those sorts for free. The feeds carry no scores or
comment counts, and anonymous reddit.com allows roughly ten requests a minute
per address, which the changelog says plainly.
The fixture is a three-entry post feed in Reddit's shape, one entry for the
post and one per comment, so the thread rendering is covered offline.
Closes#52
CONTRIBUTING described a command as a URL template only, so a contributor
adding a docs site had no way to learn that a search verb can also name a
static index (sphinx, rdoc, nodedoc), a JSON endpoint (api), or fall back
to DuckDuckGo with a site: filter, or how to pick between them. It also
still counted six files in src/.
The rust, java, ts, and php search verbs had no test; only cpp's did. #25
asked for both verbs per language to be covered offline.
The rest of the languages from #25, each probed for the cheapest shape
that works:
- go: pkg.go.dev renders search on the server, so 'search' is a plain
URL and 'pkg <path>' opens a package page.
- php: manual-lookup.php sends an exact function name straight to its
manual page, so 'fn array_map' lands on the function doc; fuzzy
search goes through DuckDuckGo since the suggestions render behind
the manual's own TOC.
- cpp: cppreference's new static site has clean /cpp/ and /c/ paths;
its native search page is bare links oc refuses as unreadable, so
'search' goes through DuckDuckGo.
- rust: std and doc page opens; rustdoc's search-index.js format is
version-fragile, so 'search' goes through DuckDuckGo.
- java: Javadoc opens pinned to javase/26, the current GA (27
redirects there); the typeSearchIndex file lacks the module names a
URL needs, so 'search' goes through DuckDuckGo.
- ts: handbook page opens; the site searches via Algolia client-side,
so DuckDuckGo again.
- learn gets a 'dotnet <api>' verb, since .NET API docs already live
there.
README table and prose and the skill notes cover the new sites.
nodejs.org has no search results page: the site's search box is a
JavaScript modal asking a third-party service, so the search verb went
through DuckDuckGo. But the API docs publish their entire reference as
one static JSON file, all.json, much the way a Sphinx site publishes
its search index, so a new nodedoc backend ranks that file locally:
every module, class, method, property, and event heading becomes a
result linking to its own anchor, and oc node search prints them as a
normal numbered page.
The file is ~8MB (~1MB over the wire) and static, so the day cache the
Sphinx backend used moves to a shared cache module both backends call:
one directory per backend, one file per host, parsed before written so
a block page never poisons it.
A typical result list costs under 100 tokens and answers from disk in
under 100ms once cached.
MDN renders its search results client-side, so 'oc mdn search' has gone
through DuckDuckGo with a site: filter. But the page it renders gets its
results from a public JSON endpoint, /api/v1/search, which returns the
site's own ranking with a summary per result in one ~11KB response. A new
'api' shortcut shape names such an endpoint and which response fields
hold the list, title, URL, and snippet; the response becomes the same
synthetic results page a Sphinx search produces and rides the normal
render path, so 'do <n>' follows a result. First view is ~520 tokens and
works for any site whose search answers as JSON.
docs.python.org has no search server: its search page downloads the
whole Sphinx index (searchindex.js, ~900KB gzipped) and ranks matches
in the browser. oc now does the same ranking itself, so 'oc py search'
answers from the site's own index instead of DuckDuckGo.
The index is cached on disk for a day and never printed; what renders
is a numbered result list that rides the normal open path, so 'do <n>'
follows a result. A query that names a symbol exactly (json.dumps)
links straight to its anchor. A site definition opts in with a
'sphinx' field naming the docs root, so any Sphinx site can use the
backend later.
First three languages from #25. Each is one definition in clis/:
- oc py library json, oc py doc reference/datamodel (the .html is
appended, matching how the aws shortcuts spell pages)
- oc mdn js Array/map, oc mdn css grid-template-columns, and a generic
oc mdn doc <path> for everything else under /en-US/docs
- oc node api fs
Python renders search client-side (Sphinx), MDN serves its search page
as a client-rendered shell with only the nav in the HTML, and nodejs.org
has no search, so all three get the DuckDuckGo site: filter fallback the
aws and gcp shortcuts already use. Short names py, mdn, and node join
the alias table; python, mozilla, nodejs, and the full domains resolve
as before through the generic rules.
The shortcuts table promised `sub <name>`, `item <id>`, `repo <owner> <name>`
and the rest for 13 sites, and clis/*.json shipped in the published `files`
list, but nothing ever read those files: `oc reddit sub ClaudeAI` answered
`unknown command 'reddit'`. The help text labels `fill` and `submit` as
planned, so an agent reading the table had every reason to treat the
shortcuts as shipped, construct one, and fall back to raw fetching when it
failed, which is the outcome this tool exists to prevent.
src/sites.js resolves `oc <site> <verb> [args]` against clis/*.json at
runtime and hands the URL to the existing open path, so a shortcut cannot
change what a page costs or how it renders, and a new definition needs no
wiring. A site answers to its domain, its bare name, and a short alias
(hn, gh, so, ddg, yt, aws, gcp, learn, finance, twitter), because an agent
that has to guess the spelling is back to guessing URLs.
Two details are worth naming. The last declared argument takes every word
after it, so `oc aws search s3 lifecycle rules` needs no quoting. And a value
filling a path segment keeps its slashes while a value in a query string does
not, so `oc learn doc azure/aks/what-is-aks` reaches that page instead of
asking the site for one impossible segment.
`oc sites` lists every site with its verbs, one line each, so discovery costs
less than a wrong guess. reddit's {sub} and github's {repo} are renamed to
{name} so the usage lines print what the README documents.
Fixes#16
only-cli