@only-cli/oc 0.5.8 → 0.5.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -85,12 +85,15 @@ Works on any mostly-static site with no per-site setup: news sites, blogs, docum
85
85
  | --- | --- | --- |
86
86
  | Hacker News | `oc hn` | `top`, `new`, `item <id>`, `user <name>` |
87
87
  | Reddit | `oc reddit` (via the Atom feeds on www.reddit.com) | `sub <name>`, `new <name>`, `top <name>`, `post <id>`, `user <name>`, `search <query>` |
88
- | GitHub | `oc gh` | `repo <owner> <name>`, `user <name>`, `search <query>`, `trending`, `issues <owner> <name>` |
88
+ | GitHub | `oc gh` (`advisories` reads the advisory database API, 60 requests an hour without a token) | `repo <owner> <name>`, `user <name>`, `search <query>`, `trending`, `issues <owner> <name>`, `advisories <ecosystem> <package>`, `issue <owner> <name> <number>`, `pr <owner> <name> <number>`, `releases <owner> <name>`, `file <owner> <name> <path>` |
89
+ | GitLab | `oc gl` (gitlab.com's API; `pr` is a merge request) | `repo <owner> <name>`, `user <name>`, `search <query>`, `issues <owner> <name>`, `issue <owner> <name> <number>`, `pr <owner> <name> <number>`, `releases <owner> <name>`, `file <owner> <name> <path>` |
90
+ | Codeberg | `oc codeberg` (the Forgejo API) | the same verbs as GitLab |
89
91
  | X | `oc x` | `user <name>`, `post <id>` |
90
92
  | LinkedIn | `oc linkedin` | `profile <name>`, `company <name>`, `jobs <query>` (public guest views) |
91
93
  | DuckDuckGo | `oc ddg` | `search <query>`, `lite <query>` |
92
94
  | Bing | `oc bing` | `search <query>`, `news <query>` |
93
95
  | Stack Overflow | `oc so` (via Atom feeds and the Stack Exchange API) | `search <query>`, `question <id>`, `tag <name>`, `user <id>`, `recent` |
96
+ | Discourse forums | `oc urlo`, `oc swift`, `oc nixos` (users.rust-lang.org, forums.swift.org, discourse.nixos.org) | `latest`, `search <query>`, `topic <id>` (the thread as Markdown) |
94
97
  | Yahoo Finance | `oc yahoo` | `quote <symbol>`, `news <symbol>`, `history <symbol>`, `lookup <query>`, `markets`, `gainers`, `losers`, `trending` |
95
98
  | YouTube | `oc yt` | `video <id>`, `channel <name>` |
96
99
  | Wikipedia | `oc wiki` (via `action=render`) | `article <title>`, `search <query>`, `lang <code> <title>` |
@@ -101,16 +104,29 @@ Works on any mostly-static site with no per-site setup: news sites, blogs, docum
101
104
  | MDN | `oc mdn` (search via the site's own API) | `js <page>`, `css <page>`, `doc <path>`, `search <query>` |
102
105
  | Node.js docs | `oc node` (search via the docs' own reference) | `api <module>`, `search <query>` |
103
106
  | Ruby docs | `oc ruby` (search via the docs' own index) | `class <class>`, `search <query>` |
107
+ | uv and Ruff docs | `oc astral` (search via the docs' own index) | `uv <query>`, `ruff <query>`, `rule <name>` |
108
+ | Polars, MkDocs, Material for MkDocs | `oc polars`, `oc mkdocs`, `oc material` (search via the docs' own index) | `search <query>` |
104
109
  | Go packages | `oc go` (pkg.go.dev, server-rendered search) | `pkg <path>`, `search <query>` |
105
110
  | PHP manual | `oc php` (an exact `fn` name lands on its page, search via DuckDuckGo) | `fn <name>`, `doc <path>`, `search <query>` |
106
111
  | Rust docs | `oc rust` (search via DuckDuckGo) | `std <path>`, `doc <path>`, `search <query>` |
107
112
  | Java docs | `oc java` (Javadoc for the current JDK, search via DuckDuckGo) | `api <path>`, `search <query>` |
108
113
  | C and C++ | `oc cpp` (cppreference.com, search via DuckDuckGo) | `cpp <path>`, `c <path>`, `search <query>` |
109
114
  | TypeScript | `oc ts` (search via DuckDuckGo) | `handbook <page>`, `search <query>` |
110
-
111
- A shortcut only ever resolves to a URL and then takes the same path `oc open` does, so it changes nothing about what a page costs or how it reads. The last argument takes every word after it, so `oc ddg search claude code cli` and `oc aws search s3 lifecycle rules` need no quoting, and a path argument keeps its slashes, so `oc learn doc azure/aks/what-is-aks` reaches that page.
112
-
113
- A few of these (X, Reddit, Stack Overflow, YouTube, Microsoft Learn search) read pages that look login-gated or JS-only from the outside, by finding the server-rendered HTML, feed, inline data, or public API the page already ships without a login. Stack Overflow search goes through the Stack Exchange API, and each result prints its `question_id`: read one with the `question <id>` feed rather than following its link, since the question page itself answers a bot challenge instead of the question. Reddit goes through the Atom feeds on www.reddit.com: old.reddit.com has sent logged-out readers to a login page since June 2026 and the `.json` views answer 403 without an OAuth token, so `oc open` on a reddit.com front page, subreddit, post, user or search URL reads the matching feed instead when no login session is held, which is also how `oc do <n>` on a post in a subreddit feed reaches its comments; `oc reddit post <id>` is the same feed by hand. oc asks reddit.com with its Firefox fingerprint first, because Reddit's edge refuses the Chrome one more often than not. The feeds carry titles, authors, dates, and bodies but no scores or comment counts, and anonymous reddit.com meters each client tightly: a second request within half a minute of the first has come back 429 in testing, and a burst of Reddit shortcuts ends in refusals that take minutes to clear, so space them out. AWS, Google Cloud, Rust, Java, TypeScript, PHP, and cppreference render docs search client-side, or as a page too bare for oc to read, so their `search` goes through DuckDuckGo with a baked-in `site:` filter instead; Go needs no such fallback, because pkg.go.dev renders its search results on the server and `oc go search` simply opens them. Python's docs are built with Sphinx, which publishes the site's full-text search index as one static file, so `oc py search` fetches that index (cached on disk for a day), ranks it locally, and prints a numbered result list; a query that names a symbol exactly, like `json.dumps`, links straight to its anchor. The same backend will work for any Sphinx site, including most Read the Docs projects. MDN also renders its search client-side, but the page gets its results from a public JSON endpoint, so `oc mdn search` asks that endpoint directly and prints the site's own ranking; that `api` shape in a site definition works for any site whose search answers as JSON. Node.js ships no search endpoint at all, but publishes its whole API reference as one static JSON file, so `oc node search` ranks that file locally the same way the Sphinx backend does, under the same day cache, and every module, class, method, property, and event heading links to its own anchor. Ruby's docs are built with RDoc, which also ships its search index as one static file, so `oc ruby search` ranks every class, method, and guide page locally the same way. PHP's manual has a lookup endpoint that sends an exact function name straight to its page, which is what `oc php fn` rides. Not supported yet: pages that only render with JavaScript and sites with hard bot challenges that expose no feed. Sites that genuinely require your account can be reached with `oc login` (bring your own cookies).
115
+ | npm | `oc npm` (the registry's JSON, trimmed to the fields that answer a dependency question) | `pkg <name>`, `version <name> <version>`, `tags <name>`, `search <query>` |
116
+ | PyPI | `oc pip` (the JSON API, search via DuckDuckGo) | `pkg <name>`, `version <name> <version>`, `search <query>` |
117
+ | crates.io | `oc cargo` (the JSON API; `docs` opens docs.rs) | `crate <name>`, `deps <name> <version>`, `docs <name>`, `search <query>` |
118
+ | RubyGems | `oc gem` (the JSON API) | `gem <name>`, `versions <name>`, `search <query>` |
119
+ | Docker Hub | `oc docker` (the v2 API) | `official <name>`, `repo <owner> <name>`, `tags <owner> <name>`, `search <query>` |
120
+ | endoflife.date | `oc eol` (the JSON API) | `product <name>`, `cycle <name> <cycle>`, `all` |
121
+ | OSV | `oc osv` (the JSON API; GHSA, CVE, and ecosystem ids all work) | `vuln <id>` |
122
+ | caniuse | `oc caniuse` (the feature files behind the site; per-browser versions stay in `oc raw`, search via DuckDuckGo) | `feature <name>`, `search <query>` |
123
+ | tldr | `oc tldr` (the tldr-pages source, one block per example) | `page <command>`, `linux <command>`, `osx <command>`, `windows <command>` |
124
+ | Linux man pages | `oc man` (man7.org, search via DuckDuckGo) | `page <section> <name>`, `search <query>` |
125
+ | RFC Editor | `oc rfc` (search via DuckDuckGo) | `rfc <number>`, `search <query>` |
126
+
127
+ A shortcut only ever resolves to a URL and then takes the same path `oc open` does, so it changes nothing about what a page costs or how it reads. The one exception is a shortcut onto a JSON API that names the fields worth reading (`keep` in its definition): `oc npm pkg react` then prints the version, license, engines, and dependencies in about 70 tokens instead of guessing from the whole record, and `oc raw` still shows every field. A plain text file (a raw source file, a tldr page, an RFC) renders one block per paragraph with its line breaks kept, and `oc raw` returns the file itself. The last argument takes every word after it, so `oc ddg search claude code cli` and `oc aws search s3 lifecycle rules` need no quoting, and a path argument keeps its slashes, so `oc learn doc azure/aks/what-is-aks` reaches that page.
128
+
129
+ A few of these (X, Reddit, Stack Overflow, YouTube, Microsoft Learn search) read pages that look login-gated or JS-only from the outside, by finding the server-rendered HTML, feed, inline data, or public API the page already ships without a login. Stack Overflow search goes through the Stack Exchange API, and each result prints its `question_id`: read one with the `question <id>` feed rather than following its link, since the question page itself answers a bot challenge instead of the question. Reddit goes through the Atom feeds on www.reddit.com: old.reddit.com has sent logged-out readers to a login page since June 2026 and the `.json` views answer 403 without an OAuth token, so `oc open` on a reddit.com front page, subreddit, post, user or search URL reads the matching feed instead when no login session is held, which is also how `oc do <n>` on a post in a subreddit feed reaches its comments; `oc reddit post <id>` is the same feed by hand. oc asks reddit.com with its Firefox fingerprint first, because Reddit's edge refuses the Chrome one more often than not. The feeds carry titles, authors, dates, and bodies but no scores or comment counts, and anonymous reddit.com meters each client tightly: a second request within half a minute of the first has come back 429 in testing, and a burst of Reddit shortcuts ends in refusals that take minutes to clear, so space them out. AWS, Google Cloud, Rust, Java, TypeScript, PHP, and cppreference render docs search client-side, or as a page too bare for oc to read, so their `search` goes through DuckDuckGo with a baked-in `site:` filter instead; Go needs no such fallback, because pkg.go.dev renders its search results on the server and `oc go search` simply opens them. Python's docs are built with Sphinx, which publishes the site's full-text search index as one static file, so `oc py search` fetches that index (cached on disk for a day), ranks it locally, and prints a numbered result list; a query that names a symbol exactly, like `json.dumps`, links straight to its anchor. The same backend will work for any Sphinx site, including most Read the Docs projects. MDN also renders its search client-side, but the page gets its results from a public JSON endpoint, so `oc mdn search` asks that endpoint directly and prints the site's own ranking; that `api` shape in a site definition works for any site whose search answers as JSON. Node.js ships no search endpoint at all, but publishes its whole API reference as one static JSON file, so `oc node search` ranks that file locally the same way the Sphinx backend does, under the same day cache, and every module, class, method, property, and event heading links to its own anchor. Ruby's docs are built with RDoc, which also ships its search index as one static file, so `oc ruby search` ranks every class, method, and guide page locally the same way. MkDocs sites publish `search/search_index.json`, one row per page and section, so `oc astral uv lockfile` and the other MkDocs shortcuts rank that file under the same day cache; a section whose title holds the query's words leads, and one matched only in its text shows a line of it. PHP's manual has a lookup endpoint that sends an exact function name straight to its page, which is what `oc php fn` rides. Not supported yet: pages that only render with JavaScript and sites with hard bot challenges that expose no feed. Sites that genuinely require your account can be reached with `oc login` (bring your own cookies).
114
130
 
115
131
  Want a website on that list? Open a pull request, or an issue naming the site; see [CONTRIBUTING.md](CONTRIBUTING.md).
116
132
 
@@ -0,0 +1,7 @@
1
+ {
2
+ "domain": "caniuse.com",
3
+ "commands": {
4
+ "feature": { "open": "https://raw.githubusercontent.com/Fyrd/caniuse/main/features-json/{name}.json", "args": ["name"], "keep": ["title", "description", "usage_perc_y", "usage_perc_a", "status", "spec", "categories", "notes", "keywords"] },
5
+ "search": { "open": "https://html.duckduckgo.com/html/?q=site%3Acaniuse.com+{query}", "args": ["query"] }
6
+ }
7
+ }
@@ -0,0 +1,13 @@
1
+ {
2
+ "domain": "codeberg.org",
3
+ "commands": {
4
+ "repo": { "open": "https://codeberg.org/api/v1/repos/{owner}/{name}", "keep": ["full_name", "description", "stars_count", "forks_count", "open_issues_count", "language", "default_branch", "topics", "updated_at", "html_url"], "args": ["owner", "name"] },
5
+ "user": { "open": "https://codeberg.org/api/v1/users/{name}/repos?limit=20", "list": "", "keep": ["{full_name} {stars_count} stars: {description}", "html_url"], "args": ["name"] },
6
+ "search": { "open": "https://codeberg.org/api/v1/repos/search?q={query}&limit=20&sort=stars&order=desc", "list": "data", "keep": ["{full_name} {stars_count} stars: {description}", "html_url"], "args": ["query"] },
7
+ "issues": { "open": "https://codeberg.org/api/v1/repos/{owner}/{name}/issues?state=open&type=issues&limit=20", "list": "", "keep": ["#{number} {title} ({comments} comments)", "html_url"], "args": ["owner", "name"] },
8
+ "issue": { "open": "https://codeberg.org/api/v1/repos/{owner}/{name}/issues/{number}", "keep": ["title", "state", "by {user.login}", "created_at", "closed_at", "comments", "html_url", "body"], "args": ["owner", "name", "number"] },
9
+ "pr": { "open": "https://codeberg.org/api/v1/repos/{owner}/{name}/pulls/{number}", "keep": ["title", "state", "by {user.login}", "{head.label} into {base.label}", "created_at", "merged_at", "comments", "html_url", "body"], "args": ["owner", "name", "number"] },
10
+ "releases": { "open": "https://codeberg.org/api/v1/repos/{owner}/{name}/releases?limit=20", "list": "", "keep": ["{tag_name} {name} {prerelease} {published_at}", "html_url"], "args": ["owner", "name"] },
11
+ "file": { "open": "https://codeberg.org/{owner}/{name}/raw/branch/HEAD/{path}", "args": ["owner", "name", "path"] }
12
+ }
13
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "domain": "crates.io",
3
+ "commands": {
4
+ "crate": { "open": "https://crates.io/api/v1/crates/{name}", "keep": ["crate.name", "crate.max_stable_version", "crate.description", "versions.0.license", "versions.0.rust_version", "versions.0.edition", "crate.documentation", "crate.repository", "crate.homepage"], "args": ["name"] },
5
+ "deps": { "open": "https://crates.io/api/v1/crates/{name}/{version}/dependencies", "list": "dependencies", "keep": ["{crate_id} {req} {kind} {optional} {target}"], "args": ["name", "version"] },
6
+ "docs": { "open": "https://docs.rs/{name}", "args": ["name"] },
7
+ "search": { "api": "https://crates.io/api/v1/crates?q={query}&per_page=20", "page": "https://crates.io/search?q={query}", "results": "crates", "fields": { "title": "name", "url": "https://docs.rs/{id}", "text": "{max_stable_version} {description}" }, "total": "meta.total", "args": ["query"] }
8
+ }
9
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "domain": "discourse.nixos.org",
3
+ "commands": {
4
+ "latest": { "open": "https://discourse.nixos.org/latest.json", "list": "topic_list.topics", "keep": ["title", "{posts_count} posts, last {last_posted_at}", "has_accepted_answer", "/raw/{id}"] },
5
+ "search": { "open": "https://discourse.nixos.org/search.json?q={query}", "list": "topics", "keep": ["title", "{posts_count} posts, started {created_at}", "has_accepted_answer", "/raw/{id}"], "args": ["query"] },
6
+ "topic": { "open": "https://discourse.nixos.org/raw/{id}", "args": ["id"] }
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "domain": "docs.astral.sh",
3
+ "commands": {
4
+ "uv": { "mkdocs": "https://docs.astral.sh/uv/", "args": ["query"] },
5
+ "ruff": { "mkdocs": "https://docs.astral.sh/ruff/", "args": ["query"] },
6
+ "rule": { "open": "https://docs.astral.sh/ruff/rules/{name}/", "args": ["name"] }
7
+ }
8
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "domain": "docs.pola.rs",
3
+ "commands": {
4
+ "search": { "mkdocs": "https://docs.pola.rs/", "args": ["query"] }
5
+ }
6
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "domain": "endoflife.date",
3
+ "commands": {
4
+ "product": { "open": "https://endoflife.date/api/{name}.json", "args": ["name"], "keep": ["cycle", "latest", "releaseDate", "support", "eol", "lts", "extendedSupport"] },
5
+ "cycle": { "open": "https://endoflife.date/api/{name}/{cycle}.json", "args": ["name", "cycle"], "keep": ["latest", "releaseDate", "support", "eol", "lts", "extendedSupport"] },
6
+ "all": { "open": "https://endoflife.date/api/all.json" }
7
+ }
8
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "domain": "forums.swift.org",
3
+ "commands": {
4
+ "latest": { "open": "https://forums.swift.org/latest.json", "list": "topic_list.topics", "keep": ["title", "{posts_count} posts, last {last_posted_at}", "has_accepted_answer", "/raw/{id}"] },
5
+ "search": { "open": "https://forums.swift.org/search.json?q={query}", "list": "topics", "keep": ["title", "{posts_count} posts, started {created_at}", "has_accepted_answer", "/raw/{id}"], "args": ["query"] },
6
+ "topic": { "open": "https://forums.swift.org/raw/{id}", "args": ["id"] }
7
+ }
8
+ }
@@ -5,6 +5,11 @@
5
5
  "user": { "open": "https://github.com/{name}", "args": ["name"] },
6
6
  "search": { "open": "https://github.com/search?q={query}&type=repositories", "args": ["query"] },
7
7
  "trending": { "open": "https://github.com/trending" },
8
- "issues": { "open": "https://github.com/{owner}/{name}/issues", "args": ["owner", "name"] }
8
+ "issues": { "open": "https://github.com/{owner}/{name}/issues", "args": ["owner", "name"] },
9
+ "issue": { "open": "https://github.com/{owner}/{name}/issues/{number}", "args": ["owner", "name", "number"] },
10
+ "pr": { "open": "https://github.com/{owner}/{name}/pull/{number}", "args": ["owner", "name", "number"] },
11
+ "releases": { "open": "https://github.com/{owner}/{name}/releases", "args": ["owner", "name"] },
12
+ "file": { "open": "https://raw.githubusercontent.com/{owner}/{name}/HEAD/{path}", "args": ["owner", "name", "path"] },
13
+ "advisories": { "open": "https://api.github.com/advisories?ecosystem={ecosystem}&affects={package}&per_page=20", "args": ["ecosystem", "package"], "keep": ["summary", "html_url", "severity", "cve_id", "vulnerabilities.0.vulnerable_version_range", "vulnerabilities.0.first_patched_version", "published_at", "withdrawn_at"] }
9
14
  }
10
15
  }
@@ -0,0 +1,13 @@
1
+ {
2
+ "domain": "gitlab.com",
3
+ "commands": {
4
+ "repo": { "open": "https://gitlab.com/api/v4/projects/{owner}%2F{name}", "keep": ["name_with_namespace", "description", "star_count", "forks_count", "default_branch", "topics", "last_activity_at", "web_url"], "args": ["owner", "name"] },
5
+ "user": { "open": "https://gitlab.com/api/v4/users/{name}/projects?per_page=20&order_by=last_activity_at", "list": "", "keep": ["{path_with_namespace} {star_count} stars: {description}", "web_url"], "args": ["name"] },
6
+ "search": { "open": "https://gitlab.com/api/v4/projects?search={query}&per_page=20&order_by=star_count", "list": "", "keep": ["{path_with_namespace} {star_count} stars: {description}", "web_url"], "args": ["query"] },
7
+ "issues": { "open": "https://gitlab.com/api/v4/projects/{owner}%2F{name}/issues?state=opened&per_page=20", "list": "", "keep": ["{references.short} {title} ({user_notes_count} comments) {labels}", "web_url"], "args": ["owner", "name"] },
8
+ "issue": { "open": "https://gitlab.com/api/v4/projects/{owner}%2F{name}/issues/{number}", "keep": ["title", "state", "by {author.username}", "labels", "created_at", "closed_at", "user_notes_count", "web_url", "description"], "args": ["owner", "name", "number"] },
9
+ "pr": { "open": "https://gitlab.com/api/v4/projects/{owner}%2F{name}/merge_requests/{number}", "keep": ["title", "state", "by {author.username}", "{source_branch} into {target_branch}", "labels", "created_at", "merged_at", "user_notes_count", "web_url", "description"], "args": ["owner", "name", "number"] },
10
+ "releases": { "open": "https://gitlab.com/api/v4/projects/{owner}%2F{name}/releases?per_page=20", "list": "", "keep": ["{tag_name} {name} {released_at}", "_links.self"], "args": ["owner", "name"] },
11
+ "file": { "open": "https://gitlab.com/{owner}/{name}/-/raw/HEAD/{path}", "args": ["owner", "name", "path"] }
12
+ }
13
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "domain": "hub.docker.com",
3
+ "commands": {
4
+ "official": { "open": "https://hub.docker.com/v2/repositories/library/{name}", "keep": ["name", "namespace", "description", "star_count", "pull_count", "last_updated"], "args": ["name"] },
5
+ "repo": { "open": "https://hub.docker.com/v2/repositories/{owner}/{name}", "keep": ["name", "namespace", "description", "star_count", "pull_count", "last_updated"], "args": ["owner", "name"] },
6
+ "tags": { "open": "https://hub.docker.com/v2/repositories/{owner}/{name}/tags?page_size=25", "list": "results", "keep": ["{name} {last_updated}"], "args": ["owner", "name"] },
7
+ "search": { "open": "https://hub.docker.com/v2/search/repositories?query={query}&page_size=20", "list": "results", "keep": ["{repo_name} {is_official} {star_count} stars: {short_description}"], "args": ["query"] }
8
+ }
9
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "domain": "man7.org",
3
+ "commands": {
4
+ "page": { "open": "https://man7.org/linux/man-pages/man{section}/{name}.{section}.html", "args": ["section", "name"] },
5
+ "search": { "open": "https://html.duckduckgo.com/html/?q=site%3Aman7.org%2Flinux%2Fman-pages+{query}", "args": ["query"] }
6
+ }
7
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "domain": "npmjs.com",
3
+ "commands": {
4
+ "pkg": { "open": "https://registry.npmjs.org/{name}/latest", "keep": ["name", "version", "description", "license", "engines.node", "homepage", "repository.url", "dependencies", "peerDependencies"], "args": ["name"] },
5
+ "version": { "open": "https://registry.npmjs.org/{name}/{version}", "keep": ["name", "version", "description", "license", "engines.node", "homepage", "repository.url", "dependencies", "peerDependencies"], "args": ["name", "version"] },
6
+ "tags": { "open": "https://registry.npmjs.org/-/package/{name}/dist-tags", "keep": ["latest", "next", "beta", "rc", "canary", "experimental"], "args": ["name"] },
7
+ "search": { "api": "https://registry.npmjs.org/-/v1/search?text={query}&size=20", "page": "https://www.npmjs.com/search?q={query}", "results": "objects", "fields": { "title": "package.name", "url": "package.links.npm", "text": "{package.version} {package.description}" }, "total": "total", "args": ["query"] }
8
+ }
9
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "domain": "osv.dev",
3
+ "commands": {
4
+ "vuln": { "open": "https://api.osv.dev/v1/vulns/{id}", "args": ["id"], "keep": ["summary", "id", "aliases", "database_specific.severity", "severity.0.score", "affected.0.package.ecosystem", "affected.0.package.name", "affected.0.ranges.0.events.1.fixed", "published", "modified", "details"] }
5
+ }
6
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "domain": "pypi.org",
3
+ "commands": {
4
+ "pkg": { "open": "https://pypi.org/pypi/{name}/json", "keep": ["info.name", "info.version", "info.summary", "info.requires_python", "info.license_expression", "info.license", "info.project_urls", "info.requires_dist"], "args": ["name"] },
5
+ "version": { "open": "https://pypi.org/pypi/{name}/{version}/json", "keep": ["info.name", "info.version", "info.summary", "info.requires_python", "info.license_expression", "info.license", "info.project_urls", "info.requires_dist"], "args": ["name", "version"] },
6
+ "search": { "open": "https://html.duckduckgo.com/html/?q=site%3Apypi.org%2Fproject+{query}", "args": ["query"] }
7
+ }
8
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "domain": "rfc-editor.org",
3
+ "commands": {
4
+ "rfc": { "open": "https://www.rfc-editor.org/rfc/rfc{number}.html", "args": ["number"] },
5
+ "search": { "open": "https://html.duckduckgo.com/html/?q=site%3Arfc-editor.org%2Frfc+{query}", "args": ["query"] }
6
+ }
7
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "domain": "rubygems.org",
3
+ "commands": {
4
+ "gem": { "open": "https://rubygems.org/api/v1/gems/{name}.json", "keep": ["name", "version", "info", "licenses", "homepage_uri", "source_code_uri", "documentation_uri", "changelog_uri"], "args": ["name"] },
5
+ "versions": { "open": "https://rubygems.org/api/v1/versions/{name}.json", "keep": ["{number} {created_at} {prerelease}"], "args": ["name"] },
6
+ "search": { "api": "https://rubygems.org/api/v1/search.json?query={query}", "page": "https://rubygems.org/search?query={query}", "results": "", "fields": { "title": "name", "url": "project_uri", "text": "{version} {info}" }, "args": ["query"] }
7
+ }
8
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "domain": "squidfunk.github.io",
3
+ "commands": {
4
+ "search": { "mkdocs": "https://squidfunk.github.io/mkdocs-material/", "args": ["query"] }
5
+ }
6
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "domain": "tldr.sh",
3
+ "commands": {
4
+ "page": { "open": "https://raw.githubusercontent.com/tldr-pages/tldr/main/pages/common/{command}.md", "args": ["command"] },
5
+ "linux": { "open": "https://raw.githubusercontent.com/tldr-pages/tldr/main/pages/linux/{command}.md", "args": ["command"] },
6
+ "osx": { "open": "https://raw.githubusercontent.com/tldr-pages/tldr/main/pages/osx/{command}.md", "args": ["command"] },
7
+ "windows": { "open": "https://raw.githubusercontent.com/tldr-pages/tldr/main/pages/windows/{command}.md", "args": ["command"] }
8
+ }
9
+ }
@@ -0,0 +1,8 @@
1
+ {
2
+ "domain": "users.rust-lang.org",
3
+ "commands": {
4
+ "latest": { "open": "https://users.rust-lang.org/latest.json", "list": "topic_list.topics", "keep": ["title", "{posts_count} posts, last {last_posted_at}", "has_accepted_answer", "/raw/{id}"] },
5
+ "search": { "open": "https://users.rust-lang.org/search.json?q={query}", "list": "topics", "keep": ["title", "{posts_count} posts, started {created_at}", "has_accepted_answer", "/raw/{id}"], "args": ["query"] },
6
+ "topic": { "open": "https://users.rust-lang.org/raw/{id}", "args": ["id"] }
7
+ }
8
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "domain": "www.mkdocs.org",
3
+ "commands": {
4
+ "search": { "mkdocs": "https://www.mkdocs.org/", "args": ["query"] }
5
+ }
6
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@only-cli/oc",
3
- "version": "0.5.8",
3
+ "version": "0.5.9",
4
4
  "description": "Turn websites into a compact CLI so AI agents can browse without burning tokens.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -8,17 +8,17 @@ description: Token-efficient web browsing and web content extraction for AI agen
8
8
  Renders a web page as a compact, numbered terminal view instead of raw HTML. A typical page is under 500 tokens.
9
9
 
10
10
  ```
11
- npx --yes @only-cli/oc@0.5.8 open <url> compact view, numbered elements
12
- npx --yes @only-cli/oc@0.5.8 do <n> follow link [n], or read it if [n] is text
13
- npx --yes @only-cli/oc@0.5.8 find <query> where a string appears, or that place itself
11
+ npx --yes @only-cli/oc@0.5.9 open <url> compact view, numbered elements
12
+ npx --yes @only-cli/oc@0.5.9 do <n> follow link [n], or read it if [n] is text
13
+ npx --yes @only-cli/oc@0.5.9 find <query> where a string appears, or that place itself
14
14
  when only one matches
15
- npx --yes @only-cli/oc@0.5.8 next next ~500 tokens of the page already open
16
- npx --yes @only-cli/oc@0.5.8 read <n> full text of region [n]
17
- npx --yes @only-cli/oc@0.5.8 raw [url] whole page as markdown (--html for cleaned HTML)
18
- npx --yes @only-cli/oc@0.5.8 login seed cookies (--cookie, --domain, --expires)
19
- npx --yes @only-cli/oc@0.5.8 logout [session] forget a session: cookies and saved page
20
- npx --yes @only-cli/oc@0.5.8 session ls list saved sessions (name, url, title)
21
- npx --yes @only-cli/oc@0.5.8 session rm [name] forget a saved session: page and cookies
15
+ npx --yes @only-cli/oc@0.5.9 next next ~500 tokens of the page already open
16
+ npx --yes @only-cli/oc@0.5.9 read <n> full text of region [n]
17
+ npx --yes @only-cli/oc@0.5.9 raw [url] whole page as markdown (--html for cleaned HTML)
18
+ npx --yes @only-cli/oc@0.5.9 login seed cookies (--cookie, --domain, --expires)
19
+ npx --yes @only-cli/oc@0.5.9 logout [session] forget a session: cookies and saved page
20
+ npx --yes @only-cli/oc@0.5.9 session ls list saved sessions (name, url, title)
21
+ npx --yes @only-cli/oc@0.5.9 session rm [name] forget a saved session: page and cookies
22
22
  ```
23
23
 
24
24
  None of these except `open`/`do`/`raw <url>` fetch anything; they replay the page `open` already saved.
@@ -34,7 +34,7 @@ oc ddg search claude code oc so question 231767 oc learn doc azur
34
34
  oc py library json oc mdn js Array/map oc node api fs
35
35
  ```
36
36
 
37
- Sites: `hn`, `reddit`, `gh`, `x`, `linkedin`, `ddg`, `bing`, `so`, `yahoo`, `yt`, `aws`, `gcp`, `learn`, `wiki`, `py`, `mdn`, `node`, `ruby`, `go`, `rust`, `java`, `php`, `cpp`, `ts`. Name one by short name, bare name, or domain (`oc hn`, `oc ycombinator`, `oc news.ycombinator.com`). The last argument takes every word after it, so a query or title needs no quoting. `oc sites` lists every site with its verbs, which is cheaper than guessing one. Reddit reads through its Atom feeds: a reddit.com page URL given to `open` meets a login wall or a 403, so use `oc reddit post <id>` or add `/.rss` to the URL, and keep Reddit calls under about ten a minute or the site answers 429.
37
+ Sites: `hn`, `reddit`, `gh`, `x`, `linkedin`, `ddg`, `bing`, `so`, `yahoo`, `yt`, `aws`, `gcp`, `learn`, `wiki`, `py`, `mdn`, `node`, `ruby`, `go`, `rust`, `java`, `php`, `cpp`, `ts`, `npm`, `pip`, `cargo`, `gem`, `docker`. Name one by short name, bare name, or domain. The last argument takes every word after it, so a query or title needs no quoting. `oc sites` lists every site with its verbs, which is cheaper than guessing one. Reddit reads through its Atom feeds: a reddit.com page URL given to `open` meets a login wall or a 403, so use `oc reddit post <id>` or add `/.rss` to the URL, and keep Reddit calls under about ten a minute or the site answers 429.
38
38
 
39
39
  Prefer a shortcut over a hand-built URL when one exists for the site, and prefer `oc wiki article <title>` over a search when you already know the article's name.
40
40
 
package/src/act.js CHANGED
@@ -157,7 +157,7 @@ export function read(n, { session = DEFAULT_SESSION, budget = 2000 } = {}) {
157
157
  // budget it still gets cut: 'up to N tokens' is a promise the page must
158
158
  // not be able to break.
159
159
  if (!lines.length && cost > budget) {
160
- lines.push(`${line.slice(0, budget * 4)} ... cut at ~${budget} tokens, raise --budget for the rest`);
160
+ lines.push(`${line.slice(0, whole(line, budget * 4))} ... cut at ~${budget} tokens, raise --budget for the rest`);
161
161
  spent += budget;
162
162
  continue;
163
163
  }
@@ -211,6 +211,12 @@ export function submit(n) {
211
211
  const BEFORE = 60;
212
212
  const SNIPPET = 200;
213
213
 
214
+ // A character past U+FFFF (an emoji, a rare CJK ideograph) is two UTF-16
215
+ // units, and an edge between them prints half of one, which a terminal shows
216
+ // as the replacement character. The compact view's cap steps back for the
217
+ // same reason (render.js); a snippet's edges and read's cut do the same.
218
+ const whole = (s, i) => (/[\uD800-\uDBFF]/.test(s[i - 1] ?? '') ? i - 1 : i);
219
+
214
220
  /**
215
221
  * Where a string appears on the current page. This is the answer to "the page
216
222
  * is long and I only care about one thing in it": one command, no fetch, and
@@ -307,8 +313,9 @@ function search(blocks, terms) {
307
313
  // One number, one line: a run of short blocks under the same handle would
308
314
  // otherwise report the same place several times.
309
315
  if (out.length && out.at(-1).n === n) continue;
310
- const start = Math.max(0, Math.min(...found) - BEFORE);
311
- const end = Math.min(block.text.length, start + SNIPPET);
316
+ const from = Math.max(0, Math.min(...found) - BEFORE);
317
+ const start = whole(block.text, from);
318
+ const end = whole(block.text, Math.min(block.text.length, from + SNIPPET));
312
319
  // One line per match is the promise the list makes, and a code block is the
313
320
  // one kind of block that carries lines of its own. They survive where they
314
321
  // are read rather than indexed: the whole-match mode above, and `read`.
package/src/apisearch.js CHANGED
@@ -12,13 +12,17 @@
12
12
 
13
13
  import { fetchPage } from './fetch.js';
14
14
  import { escapeHTML } from './sphinx.js';
15
+ import { fillTemplate, pick } from './distill.js';
15
16
 
16
17
  const MAX_RESULTS = 20;
17
18
 
18
19
  // Response fields are named by dot path ('metadata.total.value'), so a
19
- // definition can reach into whatever shape a site's API answers with.
20
- const pick = (obj, path) =>
21
- String(path).split('.').reduce((o, key) => (o == null ? undefined : o[key]), obj);
20
+ // definition can reach into whatever shape a site's API answers with, or by
21
+ // a template joining several ('{version} {description}'), which is also how
22
+ // a result gets a link when the API returns none: crates.io and npm answer
23
+ // with names, and the page for a name is a URL the definition knows.
24
+ const field = (item, spec) =>
25
+ String(spec).includes('{') ? fillTemplate(spec, item) : pick(item, spec);
22
26
 
23
27
  /**
24
28
  * The result list becomes a small HTML page, the same move sphinx.js makes
@@ -34,18 +38,24 @@ const pick = (obj, path) =>
34
38
  export function resultsToHTML(def, query, data, apiURL) {
35
39
  const host = new URL(apiURL).host;
36
40
  const fields = def.fields ?? {};
37
- const list = pick(data, def.results ?? 'results');
38
- const items = (Array.isArray(list) ? list : []).slice(0, MAX_RESULTS).map((item) => {
39
- const href = new URL(String(pick(item, fields.url ?? 'url') ?? ''), apiURL).href;
40
- const title = String(pick(item, fields.title ?? 'title') ?? href);
41
- const text = fields.text ? String(pick(item, fields.text) ?? '').trim() : '';
41
+ const picked = pick(data, def.results ?? 'results');
42
+ const list = Array.isArray(picked) ? picked : [];
43
+ const items = list.slice(0, MAX_RESULTS).map((item) => {
44
+ const href = new URL(String(field(item, fields.url ?? 'url') ?? ''), apiURL).href;
45
+ const title = String(field(item, fields.title ?? 'title') || href);
46
+ const text = fields.text ? String(field(item, fields.text) ?? '').trim() : '';
42
47
  return `<li><a href="${escapeHTML(href)}">${escapeHTML(title)}</a>`
43
48
  + `${text ? ` ${escapeHTML(text)}` : ''}</li>`;
44
49
  });
45
50
  const total = Number(def.total ? pick(data, def.total) : NaN);
46
- const count = Number.isFinite(total) && total >= items.length ? total : items.length;
51
+ // An answer with no total says only how many results it carried, and one
52
+ // cut to fit is a floor: RubyGems answers 30 a page, so "rails" read as 20
53
+ // pages matching and nothing saying the list went on.
54
+ const known = Number.isFinite(total) && total >= items.length;
55
+ const count = known ? total : list.length;
56
+ const floor = !known && count > items.length ? 'at least ' : '';
47
57
  const summary = items.length
48
- ? `${count} page${count === 1 ? '' : 's'} match, ranked by the site's own search`
58
+ ? `${floor}${count} page${count === 1 ? '' : 's'} match, ranked by the site's own search`
49
59
  + `${count > items.length ? `, top ${items.length} shown` : ''}:`
50
60
  : `nothing in the site's own search matches; try fewer or different words`;
51
61
  return `<html><head><title>${escapeHTML(host)} search: ${escapeHTML(query)}</title></head><body><main>`
package/src/cache.js CHANGED
@@ -8,15 +8,18 @@
8
8
 
9
9
  import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
10
10
  import { homedir } from 'node:os';
11
- import { extname, join } from 'node:path';
11
+ import { extname, join, posix } from 'node:path';
12
12
  import { fetchPage } from './fetch.js';
13
13
 
14
14
  const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
15
15
 
16
16
  /**
17
17
  * The file at `url`, parsed, from the disk cache while it is fresh and from
18
- * the network otherwise. One directory per backend, one file per host, kept
19
- * under the URL's own extension so the cache directory reads plainly. The
18
+ * the network otherwise. One directory per backend, one file per docs root,
19
+ * named for its host and folder and kept under the URL's own extension so
20
+ * the cache directory reads plainly. uv and Ruff both publish their docs
21
+ * under docs.astral.sh, so a name from the host alone handed one project's
22
+ * index to the other's search. The
20
23
  * file is parsed before it is written, so a block page or an error never
21
24
  * poisons the cache, and a cache that cannot be written costs nothing but
22
25
  * the refetch, the same policy session state follows.
@@ -27,7 +30,9 @@ const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
27
30
  */
28
31
  export async function cachedFile(kind, url, parse) {
29
32
  const dir = join(process.env.OC_HOME ?? join(homedir(), '.only-cli'), kind);
30
- const file = join(dir, `${new URL(url).host}${extname(new URL(url).pathname)}`);
33
+ const { host, pathname } = new URL(url);
34
+ const folder = posix.dirname(pathname).replace(/[^A-Za-z0-9.-]+/g, '_').replace(/^_+|_+$/g, '');
35
+ const file = join(dir, `${host}${folder ? `_${folder}` : ''}${extname(pathname)}`);
31
36
  try {
32
37
  if (Date.now() - statSync(file).mtimeMs < CACHE_TTL_MS) {
33
38
  return { data: parse(readFileSync(file, 'utf8')), via: 'cache' };
package/src/cli.js CHANGED
@@ -8,6 +8,7 @@ import { resolveSite, listSites } from './sites.js';
8
8
  import { sphinxSearch } from './sphinx.js';
9
9
  import { nodeSearch } from './nodedocs.js';
10
10
  import { rdocSearch } from './rdoc.js';
11
+ import { mkdocsSearch } from './mkdocs.js';
11
12
  import { apiSearch } from './apisearch.js';
12
13
  import * as act from './act.js';
13
14
  import { DEFAULT_SESSION, assertSafeName, clearSession, listSessions, loadSession, saveSession, sessionFromPage } from './session.js';
@@ -62,6 +63,7 @@ flags:
62
63
  --domain <host> login only: the hostname those cookies belong to
63
64
  --expires <dur> login only: how long the session lasts (default 1h)
64
65
  --allow-http login only: let these cookies travel over plain http
66
+ --version, -V print the installed version and exit
65
67
 
66
68
  Authenticated pages: run 'printf %s "session=..." | oc login --cookie - --domain
67
69
  example.com' to seed cookies for a session (default lifetime 1h, override with
@@ -173,9 +175,18 @@ async function main() {
173
175
  expires: { type: 'string' },
174
176
  'allow-http': { type: 'boolean', default: false },
175
177
  help: { type: 'boolean', short: 'h', default: false },
178
+ version: { type: 'boolean', short: 'V', default: false },
176
179
  },
177
180
  });
178
181
 
182
+ // Read at call time rather than baked in, so the number can never drift from
183
+ // the package that npm actually installed.
184
+ if (values.version) {
185
+ const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
186
+ console.log(pkg.version);
187
+ return;
188
+ }
189
+
179
190
  // Metrics cost tokens too, so they are opt-in: agents pass --verbose only
180
191
  // when their own verbose mode is on, or the user exports OC_VERBOSE=1.
181
192
  const verbose = values.stats || values.verbose || process.env.OC_VERBOSE === '1';
@@ -190,6 +201,11 @@ async function main() {
190
201
  // definition for, and a shortcut is only ever a URL, so it resolves to one
191
202
  // here and the rest of this function never learns it was not typed.
192
203
  let search = null;
204
+ // The fields a shortcut chose to show of a JSON response, if it chose any.
205
+ // A view is a deliberate cut, so a thin render of a heavy response is the
206
+ // choice working, not a gated page: the thin-content verdict stays out of
207
+ // it, and only a render with no text at all still fails.
208
+ let view = null;
193
209
  if (!COMMANDS.has(command)) {
194
210
  const site = resolveSite(command, args);
195
211
  if (!site) throw new Error(`unknown command '${command}', run oc --help`);
@@ -199,6 +215,7 @@ async function main() {
199
215
  command = 'search';
200
216
  } else {
201
217
  args = [site.url];
218
+ view = site.view ?? null;
202
219
  command = 'open';
203
220
  }
204
221
  }
@@ -265,7 +282,7 @@ async function main() {
265
282
  }
266
283
  const jar = jarData ? createJarHandle(sessionName, jarData) : null;
267
284
  const t0 = performance.now();
268
- const { url: finalUrl, html, status, via } = await fetchPage(url, { jar: jar ?? undefined });
285
+ const { url: finalUrl, html, status, via, type } = await fetchPage(url, { jar: jar ?? undefined });
269
286
  if (jar) saveCookieJar(sessionName, jar.toJSON());
270
287
  const fetchMs = performance.now() - t0;
271
288
  const resources = () => {
@@ -276,9 +293,9 @@ async function main() {
276
293
  };
277
294
  const htmlTokens = estimateTokens(html);
278
295
  if (values.json) {
279
- const page = distill(html, finalUrl);
296
+ const page = distill(html, finalUrl, { view, type });
280
297
  const auth = authFailure(page, finalUrl, { hadAuth });
281
- const failure = auth ?? contentFailure(contentTokens(page), htmlTokens);
298
+ const failure = auth ?? contentFailure(contentTokens(page), view ? 0 : htmlTokens);
282
299
  // Always present, so a caller can branch on the field rather than on
283
300
  // whether a field it was hoping for turned up.
284
301
  console.log(JSON.stringify({ ...page, empty: failure != null }));
@@ -293,14 +310,14 @@ async function main() {
293
310
  return;
294
311
  }
295
312
  if (command === 'raw') {
296
- const page = distill(html, finalUrl);
313
+ const page = distill(html, finalUrl, { type });
297
314
  const auth = authFailure(page, finalUrl, { hadAuth });
298
315
  if (auth) {
299
316
  if (jar) clearCookieJar(sessionName);
300
317
  noContent(finalUrl, auth);
301
318
  return;
302
319
  }
303
- const out = values.html ? toHTML(html, finalUrl) : toMarkdown(html, finalUrl);
320
+ const out = values.html ? toHTML(html, finalUrl, { type }) : toMarkdown(html, finalUrl, { type });
304
321
  const outTokens = estimateTokens(out);
305
322
  console.log(out);
306
323
  if (verbose) {
@@ -320,9 +337,9 @@ async function main() {
320
337
  }
321
338
  return;
322
339
  }
323
- const page = distill(html, finalUrl);
340
+ const page = distill(html, finalUrl, { view, type });
324
341
  const auth = authFailure(page, finalUrl, { hadAuth });
325
- const failure = auth ?? contentFailure(contentTokens(page), htmlTokens);
342
+ const failure = auth ?? contentFailure(contentTokens(page), view ? 0 : htmlTokens);
326
343
  if (auth) {
327
344
  if (jar) clearCookieJar(sessionName);
328
345
  noContent(finalUrl, auth);
@@ -350,7 +367,7 @@ async function main() {
350
367
  // follows a result. Only the list is ever printed; the index, corpus,
351
368
  // and response stay out of context.
352
369
  const t0 = performance.now();
353
- const local = { sphinx: sphinxSearch, nodedoc: nodeSearch, rdoc: rdocSearch };
370
+ const local = { sphinx: sphinxSearch, nodedoc: nodeSearch, rdoc: rdocSearch, mkdocs: mkdocsSearch };
354
371
  const kind = Object.keys(local).find((k) => search[k]);
355
372
  const { url, html, via } = kind
356
373
  ? await local[kind](search[kind], search.query)