@only-cli/oc 0.5.3 → 0.5.5

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
@@ -70,6 +70,7 @@ oc fill <n> <text> type into a numbered input (planned)
70
70
  oc submit [n] submit a form (planned)
71
71
  oc login seed cookies for a session (--cookie, --domain)
72
72
  oc logout [session] forget a session: cookies and saved page
73
+ oc session ls|rm [name] list saved sessions, or forget one (page + cookies)
73
74
  ```
74
75
 
75
76
  Flags: `--budget <tokens>` (default 500), `--json`, `--html` (raw as cleaned HTML), `--session <name>`, `--verbose`/`-v` (metrics on stderr, or export `OC_VERBOSE=1`).
@@ -107,7 +108,7 @@ Works on any mostly-static site with no per-site setup: news sites, blogs, docum
107
108
 
108
109
  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.
109
110
 
110
- 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 a reddit.com page URL handed to `oc open` still meets that wall, where `oc reddit post <id>`, or the same URL with `/.rss` on the end, reads the post and its comments. 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 allows roughly ten requests a minute per address, so a burst of Reddit shortcuts ends in a 429 that takes minutes to clear. 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).
111
+ 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).
111
112
 
112
113
  Want a website on that list? Open a pull request, or an issue naming the site; see [CONTRIBUTING.md](CONTRIBUTING.md).
113
114
 
@@ -123,15 +124,24 @@ oc open https://example.com/dashboard --session work
123
124
  oc logout work
124
125
  ```
125
126
 
127
+ Windows (PowerShell, no `printf` there):
128
+
129
+ ```powershell
130
+ $h = 'session=...; auth=...' # paste from browser devtools
131
+ $h | oc login --cookie - --domain example.com --expires 2h --session work
132
+ oc open https://example.com/dashboard --session work
133
+ oc logout work
134
+ ```
135
+
126
136
  Prefer `--cookie -`, which reads the header from stdin. The flag also takes the header inline (`--cookie "session=..."`), but an argument is a live credential in `ps` for as long as `oc` runs and in your shell history afterwards.
127
137
 
128
138
  Copy the `Cookie` header from your browser's devtools (Application → Cookies, or the Network tab on a request); a leading `Cookie:` is stripped for you. `--domain` is the site hostname those cookies belong to, and it has to be a real hostname: a bare TLD like `com` is refused, because the match is a suffix match and those cookies would go to every `.com` host the session ever fetched. Cookie names and values are checked at login too, so a stray control character fails there rather than deep inside the HTTP client.
129
139
 
130
140
  Seeded cookies are https-only. They almost always come from an https browser session, so `oc` marks them secure and never sends them over plain `http`, including on a hop an `https` page redirects into, where you never typed the downgrade. A site that really is http-only needs `--allow-http` at login. Cookies a site sets over https are pinned the same way.
131
141
 
132
- Cookies live in a separate sidecar file (`<session>.cookies.json`) under `~/.only-cli/sessions/`, mode `0600`, not in the page-state JSON and never in `--json` output. The default lifetime is one hour (`--expires 1h`), and a jar holds at most 50 cookies so a page cannot bloat it. When cookies expire or the site returns a login page, `oc` says so plainly (exit 2) instead of distilling the login form as content.
142
+ Cookies live in a separate sidecar file (`<session>.cookies.json`) under `~/.only-cli/sessions/`, owner-only (mode `0600`, or on Windows the ACL the directory hands down), not in the page-state JSON and never in `--json` output. The default lifetime is one hour (`--expires 1h`), and a jar holds at most 50 cookies so a page cannot bloat it. When cookies expire or the site returns a login page, `oc` says so plainly (exit 2) instead of distilling the login form as content.
133
143
 
134
- `oc logout` forgets the whole session, not just its cookies: a page saved under that name can hold the distilled text of something only the login could reach, so the snapshot goes with the jar.
144
+ `oc logout` forgets the whole session, not just its cookies: a page saved under that name can hold the distilled text of something only the login could reach, so the snapshot goes with the jar. `oc session rm [name]` forgets a session the same way (page plus cookies) without switching to it first, and `oc session ls` lists what is on disk (`[cookies]` marks a live jar). State lives in `~/.only-cli` (`%USERPROFILE%\.only-cli` on Windows, override with `OC_HOME`), one JSON per session plus search-index caches. Delete the directory to start over.
135
145
 
136
146
  `oc open` remembers the page it rendered in a JSON file per session under `~/.only-cli` (override with `OC_HOME`), so `oc do 3` follows `[3]` without the agent ever handling a URL. A result title on a search page is a link, so `oc do` on it opens the result rather than repeating the title. Pages longer than the budget say what they left out; `oc find`, `oc read <n>`, and `oc next` read the rest without refetching the page, and a `find` with a single match prints that region instead of the number to read it with. The budget is a target rather than a hard cap: a page that would only run a little long is printed whole rather than cut, since one extra tool call costs far more than the tokens it would have saved.
137
147
 
@@ -168,26 +178,26 @@ Private and internal addresses are refused whether or not a proxy is set. With a
168
178
 
169
179
  ## Benchmarks
170
180
 
171
- Full methodology, per-task rows, and the Codex runs live in [only-cli/benchmarks](https://github.com/only-cli/benchmarks). Where things stand (oc 0.5.1, September 2026, live sites):
181
+ Full methodology, per-task rows, and the Codex runs live in [only-cli/benchmarks](https://github.com/only-cli/benchmarks). Where things stand (oc 0.5.1 to 0.5.3, September 2026, live sites):
172
182
 
173
- - **125x fewer tokens than raw HTML** across the twelve real pages both could read: 8,519 against 1,064,474. 15x fewer than Jina Reader, 59x fewer than Playwright MCP's accessibility snapshot.
174
- - **Real content on every page it could reach, and an honest failure on the two it could not.** Reddit now sends logged-out readers to a login wall, and every other tool returned that wall, or a 403 block page, as a success. The suite hands every tool the old.reddit.com page URLs, which still end at that wall; since 0.5.2 the `oc reddit` shortcuts read the same threads through Reddit's Atom feeds, a route the suite does not measure yet. Yahoo Finance refuses plain fetch outright and DuckDuckGo still blocks lynx; oc's Chrome impersonation read both.
183
+ - **118x fewer tokens than raw HTML** across the fourteen real pages both could read: 9,466 against 1,119,003. 17x fewer than Jina Reader, 54x fewer than Playwright MCP's accessibility snapshot.
184
+ - **Real content on all fifteen pages, Reddit included.** Reddit's pages now sit behind a login wall, so the suite reads its thread and subreddit through the Atom feeds that still answer anonymously, the same route the `oc reddit` shortcuts take: 459 and 493 tokens through oc against 10,452 and 21,155 for the feed XML, while the browser-based tools and Jina Reader got the block pages Reddit serves their fingerprints. Yahoo Finance refuses plain fetch outright and DuckDuckGo still blocks lynx; oc's Chrome impersonation read both.
175
185
  - **Half the cost of Claude Code's built-in `WebSearch`** on Wikipedia lookups: $0.23 against $0.45 for five questions, both 5/5 correct, on 25x less fresh input.
176
186
  - **21% cheaper than `WebFetch` and 34% cheaper than `WebSearch`** on eleven language docs lookups, at equal or better accuracy.
177
187
  - **10% cheaper than `WebFetch` and 49% cheaper than `WebSearch`** on twelve dependency lookups across GitHub, npm, PyPI, RubyGems, crates.io, Docker Hub, Stack Overflow and an RFC, 12/12 correct with no tuned shortcut for most of those sites.
178
188
 
179
189
  The tables behind those numbers:
180
190
 
181
- **Tokens per page, no model in the loop.** Fifteen real pages: a news front page, a Reddit discussion, search results, a stock quote, three cloud CLI references, the Python, MDN, and Node.js references, and more.
191
+ **Tokens per page, no model in the loop.** Fifteen real pages: a news front page, a Reddit thread and subreddit through their Atom feeds, search results, a stock quote, three cloud CLI references, the Python, MDN, and Node.js references, and more.
182
192
 
183
193
  | method | tokens for 15 pages | notes |
184
194
  | --- | ---: | --- |
185
- | `oc open` | 8,971 | real content on 13 of 15 pages; the two Reddit pages are behind a login wall, and oc is the only reader that reported that instead of returning the wall |
186
- | Jina Reader | 105,198 | both Reddit results are block pages; failed LinkedIn and the Node.js `fs` page outright |
187
- | Playwright MCP | 531,303 | accessibility snapshots; both Reddit snapshots are the login wall |
188
- | raw HTML fetch | 1,240,669 | both Reddit results are the login wall, 88,000 tokens of it each; Yahoo Finance refused the connection |
195
+ | `oc open` | 9,913 | real content on all 15 pages; the two Reddit feeds cost 459 and 493 tokens |
196
+ | Jina Reader | 145,679 | both Reddit results are block pages; failed LinkedIn outright |
197
+ | Playwright MCP | 535,908 | accessibility snapshots; both Reddit snapshots are block pages, since Reddit refuses the Chrome fingerprint |
198
+ | raw HTML fetch | 1,119,003 | the two Reddit feeds are 10,452 and 21,155 tokens of XML; Yahoo Finance refused the connection |
189
199
 
190
- oc's budget keeps every page near 500 tokens however much it weighs: the YouTube watch page is 345,487 tokens raw and 688 through oc, Node's `fs` reference 275,425 against 479. On the twelve pages both could read, raw HTML costs 125x what oc does: 1,064,474 against 8,519.
200
+ oc's budget keeps every page near 500 tokens however much it weighs: the YouTube watch page is 363,516 tokens raw and 688 through oc, Node's `fs` reference 275,425 against 479. On the fourteen pages both could read, raw HTML costs 118x what oc does: 1,119,003 against 9,466. Reddit meters anonymous feed readers, so the suite spaces its Reddit requests a minute apart; a second request from the same client inside thirty seconds came back 429 in every faster pass.
191
201
 
192
202
  **Whole tasks against the agent's built-in web tools.** Read cost is one thing, what an agent actually spends is another, so a second set of suites runs full lookups end to end in Claude Code (`claude-sonnet-5`), one tool per run, and grades every answer. Five Wikipedia lookups, eleven language documentation lookups, and twelve lookups on the pages around a dependency, where oc has shortcuts only for GitHub and Stack Overflow and renders the rest generically:
193
203
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@only-cli/oc",
3
- "version": "0.5.3",
3
+ "version": "0.5.5",
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,15 +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.3 open <url> compact view, numbered elements
12
- npx --yes @only-cli/oc@0.5.3 do <n> follow link [n], or read it if [n] is text
13
- npx --yes @only-cli/oc@0.5.3 find <query> where a string appears, or that place itself
11
+ npx --yes @only-cli/oc@0.5.5 open <url> compact view, numbered elements
12
+ npx --yes @only-cli/oc@0.5.5 do <n> follow link [n], or read it if [n] is text
13
+ npx --yes @only-cli/oc@0.5.5 find <query> where a string appears, or that place itself
14
14
  when only one matches
15
- npx --yes @only-cli/oc@0.5.3 next next ~500 tokens of the page already open
16
- npx --yes @only-cli/oc@0.5.3 read <n> full text of region [n]
17
- npx --yes @only-cli/oc@0.5.3 raw [url] whole page as markdown (--html for cleaned HTML)
18
- npx --yes @only-cli/oc@0.5.3 login seed cookies (--cookie, --domain, --expires)
19
- npx --yes @only-cli/oc@0.5.3 logout [session] forget a session: cookies and saved page
15
+ npx --yes @only-cli/oc@0.5.5 next next ~500 tokens of the page already open
16
+ npx --yes @only-cli/oc@0.5.5 read <n> full text of region [n]
17
+ npx --yes @only-cli/oc@0.5.5 raw [url] whole page as markdown (--html for cleaned HTML)
18
+ npx --yes @only-cli/oc@0.5.5 login seed cookies (--cookie, --domain, --expires)
19
+ npx --yes @only-cli/oc@0.5.5 logout [session] forget a session: cookies and saved page
20
+ npx --yes @only-cli/oc@0.5.5 session ls list saved sessions (name, url, title)
21
+ npx --yes @only-cli/oc@0.5.5 session rm [name] forget a saved session: page and cookies
20
22
  ```
21
23
 
22
24
  None of these except `open`/`do`/`raw <url>` fetch anything; they replay the page `open` already saved.
@@ -86,10 +88,23 @@ oc open https://example.com/dashboard --session work
86
88
  oc logout work
87
89
  ```
88
90
 
91
+ Windows (PowerShell, no `printf`):
92
+
93
+ ```powershell
94
+ $h = 'session=...; auth=...'
95
+ $h | oc login --cookie - --domain example.com --expires 2h --session work
96
+ oc open https://example.com/dashboard --session work
97
+ oc logout work
98
+ ```
99
+
89
100
  Pass `--cookie -` and pipe the header in, as above: an inline `--cookie "session=..."` puts a live credential in `ps` and in shell history. Copy the header from browser devtools. `--domain` must be a real hostname; a bare TLD like `com` is refused, since the cookies would then go to every `.com` host the session fetched.
90
101
 
91
102
  Default lifetime is 1h. Seeded cookies are https-only: they are never sent over plain `http`, including on a redirect that downgrades, unless you seeded them with `--allow-http`. When cookies expire or the site returns a login page, `oc` says so (exit 2) instead of rendering the login form as content. Cookies live in a separate file from page state and are never included in `--json` output. `oc logout` drops that session's saved page along with its cookies.
92
103
 
104
+ ## Saved sessions live on disk
105
+
106
+ State is one JSON per session under `~/.only-cli/sessions/` (`%USERPROFILE%\.only-cli\sessions\` on Windows, `OC_HOME` overrides). `session ls` shows what accumulated; `session rm [name]` drops a session's page and cookies (same promise as `logout`). Deleting the directory starts over.
107
+
93
108
  ## When not to use it
94
109
 
95
110
  Pages needing heavy client-side JS aren't supported yet. A page with no readable text (JavaScript-only, a consent wall, a bot challenge) prints one line on stderr and exits 2, which is distinct from the exit 1 every other failure uses, so exit 2 means "oc cannot read this one" rather than "this page is empty". Take it at its word: say so and fall back to another tool rather than retrying the same URL.
package/src/cli.js CHANGED
@@ -10,7 +10,7 @@ import { nodeSearch } from './nodedocs.js';
10
10
  import { rdocSearch } from './rdoc.js';
11
11
  import { apiSearch } from './apisearch.js';
12
12
  import * as act from './act.js';
13
- import { DEFAULT_SESSION, assertSafeName, clearSession, loadSession, saveSession, sessionFromPage } from './session.js';
13
+ import { DEFAULT_SESSION, assertSafeName, clearSession, listSessions, loadSession, saveSession, sessionFromPage } from './session.js';
14
14
  import { authFailure, sessionExpiredMessage } from './auth.js';
15
15
  import {
16
16
  loadCookieJar,
@@ -42,7 +42,7 @@ usage: oc <command> [args] [flags]
42
42
  back return to the previous page (planned)
43
43
  login seed cookies for a session (--cookie, --domain)
44
44
  logout [session] forget a session: its cookies and its saved page
45
- session ls|rm manage saved sessions (planned)
45
+ session ls|rm [name] list saved sessions, or forget one (page + cookies)
46
46
 
47
47
  flags:
48
48
  --budget <tokens> tighten or loosen the render budget (default 500,
@@ -111,6 +111,21 @@ const noContent = (url, detail, hint = "; 'oc raw' has the page's markdown if th
111
111
  process.exitCode = NO_CONTENT_EXIT;
112
112
  };
113
113
 
114
+ /**
115
+ * Forget everything saved under a name, for `oc logout` and `oc session rm`.
116
+ * The page saved under a name can be the distilled text of a page only the
117
+ * cookies could reach, so the two go together: after either command nothing
118
+ * of that login remains. Cookies go first so a failure on the page file never
119
+ * leaves the credential behind.
120
+ * @param {string} name
121
+ * @returns {boolean} whether anything was on disk to forget
122
+ */
123
+ function forgetSession(name) {
124
+ const hadJar = clearCookieJar(name);
125
+ const hadPage = clearSession(name);
126
+ return hadJar || hadPage;
127
+ }
128
+
114
129
  const LOGIN_USAGE = 'usage: printf %s "session=..." | oc login --cookie - --domain example.com'
115
130
  + ' [--expires 1h] [--session name] [--allow-http]';
116
131
 
@@ -208,11 +223,7 @@ async function main() {
208
223
  }
209
224
 
210
225
  if (command === 'logout') {
211
- const name = args[0] ? assertSafeName(args[0]) : sessionName;
212
- clearCookieJar(name);
213
- // The page saved under this name can be the distilled text of a page only
214
- // the cookies could reach, so logout drops it too.
215
- clearSession(name);
226
+ forgetSession(args[0] ? assertSafeName(args[0]) : sessionName);
216
227
  return;
217
228
  }
218
229
 
@@ -261,7 +272,7 @@ async function main() {
261
272
  const processMs = performance.now() - t0 - fetchMs;
262
273
  const rss = process.memoryUsage().rss;
263
274
  return `HTTP ${status} via ${via}, fetch ${Math.round(fetchMs)}ms, process ${Math.round(processMs)}ms, `
264
- + `${Math.round(html.length / 1024)}KB transferred, ${Math.round(rss / 1048576)}MB memory`;
275
+ + `${Math.round(Buffer.byteLength(html) / 1024)}KB transferred, ${Math.round(rss / 1048576)}MB memory`;
265
276
  };
266
277
  const htmlTokens = estimateTokens(html);
267
278
  if (values.json) {
@@ -365,7 +376,31 @@ async function main() {
365
376
  case 'submit': return act.submit(args[0] ? Number(args[0]) : undefined);
366
377
  case 'back': return act.back();
367
378
  case 'sites': return console.log(listSites());
368
- case 'session': throw new act.NotImplemented('session');
379
+ case 'session': {
380
+ // Saved sessions accumulate on disk (one JSON per page kept for
381
+ // do/read/next), so agents can inspect and drop them without guessing
382
+ // paths under ~/.only-cli. With no name, rm targets --session.
383
+ const [sub, target] = args;
384
+ if (sub === 'ls') {
385
+ const list = listSessions();
386
+ if (values.json) return console.log(JSON.stringify(list));
387
+ if (!list.length) return console.log('no saved sessions');
388
+ for (const s of list) {
389
+ console.log(`${s.name}${s.url ? ` ${s.url}` : ''}${s.title ? ` (${s.title})` : ''}${s.cookies ? ' [cookies]' : ''}`);
390
+ }
391
+ return;
392
+ }
393
+ if (sub === 'rm') {
394
+ const name = target ? assertSafeName(target) : sessionName;
395
+ // A name nothing was saved under is most likely a typo, and an agent
396
+ // that reads "forgot session" would move on believing the login is
397
+ // gone, so rm fails loud instead of succeeding at nothing.
398
+ if (!forgetSession(name)) throw new Error(`no such session '${name}', run oc session ls`);
399
+ if (values.json) return console.log(JSON.stringify({ forgotten: name }));
400
+ return console.log(`forgot session '${name}'`);
401
+ }
402
+ throw new Error(`usage: oc session ls|rm [name]`);
403
+ }
369
404
  default:
370
405
  throw new Error(`unknown command '${command}', run oc --help`);
371
406
  }
package/src/cookies.js CHANGED
@@ -5,9 +5,9 @@
5
5
 
6
6
  import net from 'node:net';
7
7
  import { join } from 'node:path';
8
- import { mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync, chmodSync } from 'node:fs';
8
+ import { readFileSync, writeFileSync, unlinkSync, readdirSync, chmodSync } from 'node:fs';
9
9
 
10
- import { sessionDir, assertSafeName } from './session.js';
10
+ import { sessionDir, ensureSessionDir, assertSafeName, COOKIE_JAR_SUFFIX } from './session.js';
11
11
 
12
12
  const DEFAULT_EXPIRES_MS = 60 * 60 * 1000; // 1h
13
13
  export { DEFAULT_EXPIRES_MS };
@@ -53,7 +53,7 @@ function clip(value) {
53
53
  * @returns {string}
54
54
  */
55
55
  export function cookieJarPath(name) {
56
- return join(sessionDir(), `${assertSafeName(name)}.cookies.json`);
56
+ return join(sessionDir(), `${assertSafeName(name)}${COOKIE_JAR_SUFFIX}`);
57
57
  }
58
58
 
59
59
  /**
@@ -256,7 +256,7 @@ export function loadCookieJar(name) {
256
256
  * @param {CookieJar} jar
257
257
  */
258
258
  export function saveCookieJar(name, jar) {
259
- mkdirSync(sessionDir(), { recursive: true });
259
+ ensureSessionDir();
260
260
  // writeFileSync only sets the mode on create, so an existing sidecar has its
261
261
  // owner-only mode reasserted on every save.
262
262
  const path = cookieJarPath(name);
@@ -265,13 +265,18 @@ export function saveCookieJar(name, jar) {
265
265
  }
266
266
 
267
267
  /**
268
+ * Only a missing jar is fine to ignore: any other failure leaves a live
269
+ * credential on disk that the caller may be about to report as gone.
268
270
  * @param {string} name
271
+ * @returns {boolean} whether a jar was removed
269
272
  */
270
273
  export function clearCookieJar(name) {
271
274
  try {
272
275
  unlinkSync(cookieJarPath(name));
273
- } catch {
274
- // missing file is fine
276
+ return true;
277
+ } catch (err) {
278
+ if (err?.code === 'ENOENT') return false;
279
+ throw err;
275
280
  }
276
281
  }
277
282
 
@@ -287,12 +292,13 @@ export function purgeExpiredJars() {
287
292
  return;
288
293
  }
289
294
  for (const file of readdirSync(dir)) {
290
- if (!file.endsWith('.cookies.json')) continue;
291
- const name = file.slice(0, -'.cookies.json'.length);
295
+ if (!file.endsWith(COOKIE_JAR_SUFFIX)) continue;
292
296
  try {
293
297
  const jar = /** @type {CookieJar} */ (JSON.parse(readFileSync(join(dir, file), 'utf8')));
294
- if (isSessionExpired(jar)) clearCookieJar(name);
298
+ if (isSessionExpired(jar)) unlinkSync(join(dir, file));
295
299
  } catch {
300
+ // A jar that will not parse is as useless as an expired one, and a sweep
301
+ // that cannot delete a file has nothing to report: the next one retries.
296
302
  try { unlinkSync(join(dir, file)); } catch {}
297
303
  }
298
304
  }
package/src/distill.js CHANGED
@@ -504,9 +504,15 @@ export function feedToHTML(text) {
504
504
  // HTML itself, ready to be embedded and parsed like any page.
505
505
  const body = (entry.querySelector('content') ?? entry.querySelector('summary') ?? entry.querySelector('description'))?.textContent ?? '';
506
506
  parts.push('<article>');
507
- if (title) parts.push(`<h2>${esc(title)}</h2>`);
508
- if (byline || href) {
509
- parts.push(`<p>${esc(byline)}${href ? ` <a href="${esc(href)}">open</a>` : ''}</p>`);
507
+ // The title is the link. It used to sit beside the byline as an anchor
508
+ // labelled "open", the same label on every entry, and the repeated-controls
509
+ // filter hid the lot as chrome, so nothing in a subreddit feed led to a
510
+ // post: `do <n>` on one read its heading instead of following it (#59). A
511
+ // heading that is exactly one anchor becomes a followable heading in the
512
+ // walk, so the number the agent already sees is the one that opens it.
513
+ if (title) parts.push(`<h2>${href ? `<a href="${esc(href)}">${esc(title)}</a>` : esc(title)}</h2>`);
514
+ if (byline || (href && !title)) {
515
+ parts.push(`<p>${esc(byline)}${href && !title ? ` <a href="${esc(href)}">open</a>` : ''}</p>`);
510
516
  }
511
517
  parts.push(body, '</article>');
512
518
  }
package/src/fetch.js CHANGED
@@ -73,6 +73,103 @@ export function assertReadableType(type) {
73
73
  throw new Error(`not a page oc can read (${type.split(';')[0].trim()}), it renders HTML, XML feeds, JSON, and plain text`);
74
74
  }
75
75
 
76
+ // A body read as UTF-8 whatever it declares turns each non-ASCII character of
77
+ // a Shift_JIS, EUC-KR, GBK, or windows-1252 page into U+FFFD, noise an agent
78
+ // pays for and cannot read. So the encoding is looked for where a browser
79
+ // looks: the Content-Type header, then a <meta> tag, which the HTML spec
80
+ // requires within the first 1024 bytes, or a feed's XML declaration.
81
+ // The comma is excluded because a duplicated Content-Type header arrives from
82
+ // headers.get as one value joined by ", ", and a label with a comma stuck to
83
+ // its end is one TextDecoder refuses.
84
+ const CHARSET_PARAM = /;\s*charset\s*=\s*["']?([^"';,\s]+)/i;
85
+ const XML_ENCODING = /^\s*<\?xml\b[^>]*?\bencoding\s*=\s*["']([^"']+)/;
86
+ // One tag's attributes, quoted values kept whole, so a charset written inside
87
+ // another attribute's value (an og:url carrying a query string, say) stays
88
+ // part of that value instead of reading as a declaration.
89
+ const ATTRS = /([^\s=/>]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s>]*))?/g;
90
+ // Only markup declares an encoding in its own text, so only markup is read for
91
+ // one. JSON is UTF-8 by definition (RFC 8259), which is why a browser ignores
92
+ // a charset on it, and plain text or JavaScript carries no declaration a
93
+ // scan could find, only strings that look like one.
94
+ const MARKUP_TYPE = /^\s*(?:text\/(?:html|xml)|application\/(?:xml|[\w.+-]*\+xml))/i;
95
+ const JSON_TYPE = /^\s*(?:application\/(?:json|x-ndjson|[\w.+-]*\+json)|text\/json)/i;
96
+
97
+ // TextDecoder knows the labels browsers do, so no dependency is needed, and it
98
+ // refuses the ones they do not, which then fall through to the next place a
99
+ // label can come from.
100
+ const UTF8 = new TextDecoder();
101
+ const decoderFor = (label) => {
102
+ try {
103
+ return label ? new TextDecoder(label) : null;
104
+ } catch {
105
+ return null;
106
+ }
107
+ };
108
+
109
+ /**
110
+ * The charset one <meta> tag declares: the attribute browsers read first, then
111
+ * the older http-equiv form, which only counts on a content-type, not on any
112
+ * content attribute that happens to mention a charset.
113
+ * @param {string} tag
114
+ * @returns {string | null}
115
+ */
116
+ function metaLabel(tag) {
117
+ const attrs = new Map();
118
+ for (const [, name, value = ''] of tag.slice('<meta'.length).matchAll(ATTRS)) {
119
+ attrs.set(name.toLowerCase(), value.replace(/^(["'])([\s\S]*)\1$/, '$2').trim());
120
+ }
121
+ const charset = attrs.get('charset');
122
+ if (charset) return charset;
123
+ if (attrs.get('http-equiv')?.toLowerCase() !== 'content-type') return null;
124
+ return attrs.get('content')?.match(CHARSET_PARAM)?.[1] ?? null;
125
+ }
126
+
127
+ /**
128
+ * The decoder a page asks for, read the way a browser's prescan reads it
129
+ * rather than with one regex over the head: a label written inside a comment,
130
+ * a <script> string, or another tag's attribute is not a declaration, and
131
+ * decoding by one of those is how a page that was already readable turns to
132
+ * mojibake. A label TextDecoder refuses is not the end of the search, so a
133
+ * feed declaring `cp949` still gets the <meta> tag underneath it.
134
+ * @param {string} head - the first 1024 bytes as latin1
135
+ * @returns {TextDecoder | null}
136
+ */
137
+ function decoderInPage(head) {
138
+ const xml = decoderFor(head.match(XML_ENCODING)?.[1]);
139
+ if (xml) return xml;
140
+ const markup = head
141
+ .replace(/<!--[\s\S]*?(?:-->|$)/g, ' ')
142
+ .replace(/<script\b[\s\S]*?(?:<\/script>|$)/gi, ' ');
143
+ // Every tag is consumed whole, so a <meta> written inside a quoted attribute
144
+ // value belongs to the tag quoting it and is never read as a tag itself.
145
+ for (const [tag] of markup.matchAll(/<[a-zA-Z][^>]*>?/g)) {
146
+ const decoder = /^<meta\b/i.test(tag) ? decoderFor(metaLabel(tag)) : null;
147
+ if (decoder) return decoder;
148
+ }
149
+ return null;
150
+ }
151
+
152
+ /**
153
+ * A body as text in the encoding it declares, header first, then the page.
154
+ * With neither, or only labels no browser knows, it is UTF-8, which is what
155
+ * oc assumed for every page before.
156
+ * @param {Buffer} bytes
157
+ * @param {string | null | undefined} type - the content-type header
158
+ * @returns {string}
159
+ */
160
+ export function decodeBody(bytes, type) {
161
+ const declared = JSON_TYPE.test(type ?? '') ? null : decoderFor(type?.match(CHARSET_PARAM)?.[1]);
162
+ if (declared) return declared.decode(bytes);
163
+ // A missing header is not a refusal anywhere else in oc and is common on
164
+ // small servers, so a body that names no type is still read for one.
165
+ if (type && !MARKUP_TYPE.test(type)) return UTF8.decode(bytes);
166
+ const inPage = decoderInPage(bytes.toString('latin1', 0, 1024));
167
+ // A label found by reading the bytes as ASCII cannot be UTF-16, whose ASCII
168
+ // is interleaved with zero bytes, so the HTML spec reads that claim as UTF-8.
169
+ if (!inPage || inPage.encoding.startsWith('utf-16')) return UTF8.decode(bytes);
170
+ return inPage.decode(bytes);
171
+ }
172
+
76
173
  // IPv4 ranges with no business receiving a server-initiated fetch: loopback,
77
174
  // link-local, the three RFC 1918 private blocks, carrier-grade NAT, the
78
175
  // unspecified/broadcast addresses, and the documentation/benchmark ranges.
@@ -355,7 +452,7 @@ function wrapNodeResponse(res, url) {
355
452
  }
356
453
  chunks.push(c);
357
454
  });
358
- res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
455
+ res.on('end', () => resolve(decodeBody(Buffer.concat(chunks), headers.get('content-type'))));
359
456
  res.on('error', reject);
360
457
  });
361
458
  const status = res.statusCode ?? 0;
@@ -497,7 +594,10 @@ export function proxyGet(url, proxy, headers = {}, tlsOpts = {}) {
497
594
  * identity got the page (impers:chrome, impers:firefox, or fetch)
498
595
  */
499
596
  export async function fetchPage(url, { jar } = {}) {
500
- const target = /^https?:\/\//i.test(url) ? url : `https://${url}`;
597
+ let target = /^https?:\/\//i.test(url) ? url : `https://${url}`;
598
+ // A reader with no cookies for reddit.com gets the feed where the page
599
+ // would be a login wall; one who logged in gets the page it asked for.
600
+ if (!jar?.cookieHeaderFor(target)) target = redditFeedURL(target) ?? target;
501
601
  await assertSafeTarget(target);
502
602
  const impers = await loadImpers();
503
603
  return impers ? viaImpers(impers, target, jar) : viaFetch(target, jar);
@@ -562,6 +662,39 @@ function captureSetCookie(jar, url, res) {
562
662
  // entry.
563
663
  const FIREFOX_FIRST_HOSTS = ['reddit.com'];
564
664
 
665
+ // Reddit has sent logged-out readers of its HTML pages to a login page since
666
+ // June 2026 (#52), while the Atom feed beside each of those pages still
667
+ // answers. A feed entry links to the page, so following a post out of a
668
+ // subreddit feed used to land on the wall. The front page, subreddit
669
+ // listings, posts, user pages and search are mapped to their feeds here;
670
+ // anything else on reddit.com is fetched as asked.
671
+ const REDDIT_HOSTS = ['reddit.com', 'www.reddit.com', 'old.reddit.com', 'new.reddit.com', 'np.reddit.com'];
672
+ const SEG = '[A-Za-z0-9_.-]+';
673
+ const REDDIT_FEED_PATHS = new RegExp(
674
+ `^(?:|/r/${SEG}(?:/(?:new|top|hot|rising))?|/(?:r/${SEG}/)?comments/${SEG}(?:/${SEG}){0,2}|/u(?:ser)?/${SEG})$`,
675
+ );
676
+
677
+ /**
678
+ * The www.reddit.com Atom feed for a reddit.com page URL, or null when the URL
679
+ * is not one of the page shapes that has a feed, or is a feed already.
680
+ * @param {string} target
681
+ * @returns {string | null}
682
+ */
683
+ export function redditFeedURL(target) {
684
+ let u;
685
+ try {
686
+ u = new URL(target);
687
+ } catch {
688
+ return null;
689
+ }
690
+ if (!REDDIT_HOSTS.includes(u.hostname.toLowerCase())) return null;
691
+ const path = u.pathname.replace(/\/+$/, '');
692
+ if (/\.(?:rss|json|xml)$/i.test(path)) return null;
693
+ if (path === '/search') return `https://www.reddit.com/search.rss${u.search}`;
694
+ if (!REDDIT_FEED_PATHS.test(path)) return null;
695
+ return `https://www.reddit.com${path.replace(/^\/u\//, '/user/')}/.rss${u.search}`;
696
+ }
697
+
565
698
  /**
566
699
  * The order in which impers identities are tried for a URL.
567
700
  * @param {string} target
@@ -578,6 +711,17 @@ export function identityOrder(target) {
578
711
  return firefoxFirst ? ['firefox', 'chrome'] : ['chrome', 'firefox'];
579
712
  }
580
713
 
714
+ // impers throws out of its own `content` getter when a response is streaming
715
+ // instead of buffered, so the question has to be asked inside a try: the answer
716
+ // is the bytes it holds, or nothing, never an error from a getter.
717
+ const bufferedContent = (res) => {
718
+ try {
719
+ return Buffer.isBuffer(res.content) ? res.content : null;
720
+ } catch {
721
+ return null;
722
+ }
723
+ };
724
+
581
725
  /**
582
726
  * Fetch a page through impers, downgrading identity when one is refused.
583
727
  * Exported so the downgrade chain can be proven against a fake impers; the
@@ -628,7 +772,18 @@ export async function viaImpers(impers, target, jar) {
628
772
  assertBodySize(Number(res.headers.get('content-length')) || 0, target);
629
773
  // impers buffers inside its own binding, so the size of what it already
630
774
  // holds is all there is to check; the bound still stops an oversized body
631
- // from travelling any further.
775
+ // from travelling any further. impers decodes a few Western charsets itself
776
+ // and reads every other one as UTF-8, so the bytes it keeps in `content` are
777
+ // decoded here instead, the way the fetch transport's are.
778
+ const bytes = bufferedContent(res);
779
+ if (bytes) {
780
+ // What arrived, not what it decodes to: a CJK page is about half as many
781
+ // characters as it is bytes, and with the Content-Length above optional
782
+ // this is the only size this transport ever really checks. Refused before
783
+ // the decode so an oversized body is not allocated twice over.
784
+ assertBodySize(bytes.length, target);
785
+ return { url: res.url ?? target, html: decodeBody(bytes, res.headers.get('content-type')), status, via };
786
+ }
632
787
  const html = typeof res.text === 'function' ? await res.text() : String(res.text ?? res.body ?? '');
633
788
  assertBodySize(html.length, target);
634
789
  return { url: res.url ?? target, html, status, via };
@@ -670,5 +825,5 @@ export async function readBody(res, url) {
670
825
  assertBodySize(size, url);
671
826
  chunks.push(chunk);
672
827
  }
673
- return Buffer.concat(chunks).toString('utf8');
828
+ return decodeBody(Buffer.concat(chunks), res.headers.get('content-type'));
674
829
  }
package/src/session.js CHANGED
@@ -12,26 +12,67 @@
12
12
 
13
13
  import { homedir } from 'node:os';
14
14
  import { join } from 'node:path';
15
- import { mkdirSync, readFileSync, writeFileSync, chmodSync, unlinkSync } from 'node:fs';
15
+ import { mkdirSync, readFileSync, writeFileSync, chmodSync, unlinkSync, readdirSync } from 'node:fs';
16
16
 
17
17
  export const DEFAULT_SESSION = 'default';
18
18
 
19
+ // The cookie sidecar sits next to the page file as `<name>.cookies.json`
20
+ // (see cookies.js). Both modules split filenames on this suffix, so it lives
21
+ // in one place: a rename that reached only one of them would make `session
22
+ // ls` list jars as pages, and `session rm` unlink a jar as a page.
23
+ export const COOKIE_JAR_SUFFIX = '.cookies.json';
24
+
19
25
  // OC_HOME relocates the whole state directory, for sandboxes, CI, and tests.
20
26
  export const sessionDir = () => join(process.env.OC_HOME ?? join(homedir(), '.only-cli'), 'sessions');
21
27
 
28
+ /**
29
+ * The store directory is what decides who can reach a session: an owner-only
30
+ * mode on a cookie jar is worth nothing inside a directory another local
31
+ * account can list, write to, or unlink from, which is what a permissive umask
32
+ * (0 or 002, the default in some container and CI images) leaves behind. mkdir
33
+ * applies its mode only to a directory it creates, so one already on disk is
34
+ * tightened too, the way the files in it are on every save.
35
+ * @returns {string} the store directory, now present and owner-only
36
+ */
37
+ export function ensureSessionDir() {
38
+ const dir = sessionDir();
39
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
40
+ try {
41
+ chmodSync(dir, 0o700);
42
+ } catch {
43
+ // A shared OC_HOME that oc does not own keeps the mode it has rather than
44
+ // failing the save; the files written into it are still owner-only.
45
+ }
46
+ return dir;
47
+ }
48
+
22
49
  // A session name is interpolated straight into a filename, and the cookie
23
50
  // sidecar it names now holds real credentials, so a name that is a path
24
51
  // (absolute, or with a separator or '..') could write or delete a file outside
25
52
  // the store. Names are user-facing labels, so this charset loses nothing real.
26
53
  const SAFE_NAME = /^[A-Za-z0-9._-]+$/;
27
54
 
55
+ // Win32 reads a path component as a device when the part before its first
56
+ // period is a reserved name, which would put session 'nul''s cookie jar on the
57
+ // NUL device rather than in a file. Node 24 on Windows 11 writes a real file
58
+ // there (libuv's path handling sidesteps the rule, tested both ways), so this
59
+ // guards the name rather than fixing a failure oc has today: an older Windows,
60
+ // another runtime, or a path that reaches a shell still reads them as devices.
61
+ const DEVICE_NAME = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
62
+
63
+ // A name ending in '.cookies' would save its page at `<x>.cookies.json`, the
64
+ // path of session `<x>`'s cookie jar, so `oc logout x` would delete it and
65
+ // `oc session ls` would hide it.
66
+ const isSafeName = (name) => typeof name === 'string' && name !== '.' && name !== '..'
67
+ && !name.endsWith('.cookies') && !DEVICE_NAME.test(name.split('.')[0]) && SAFE_NAME.test(name);
68
+
28
69
  /**
29
70
  * @param {string} name
30
71
  * @returns {string} the same name, once it is known to be a safe filename
31
72
  */
32
73
  export function assertSafeName(name) {
33
- if (typeof name !== 'string' || name === '.' || name === '..' || !SAFE_NAME.test(name)) {
34
- throw new Error(`invalid session name '${name}', use letters, numbers, '.', '-', or '_'`);
74
+ if (!isSafeName(name)) {
75
+ throw new Error(`invalid session name '${name}', use letters, numbers, '.', '-', or '_' (not ending in '.cookies', not a device name like 'nul')`);
35
76
  }
36
77
  return name;
37
78
  }
@@ -153,7 +194,7 @@ export function handleNumbers(state) {
153
194
  * @param {object} state
154
195
  */
155
196
  export function saveSession(name, state) {
156
- mkdirSync(sessionDir(), { recursive: true });
197
+ ensureSessionDir();
157
198
  // A snapshot of an authenticated page holds that page's text, so it gets the
158
199
  // same owner-only mode as the cookie sidecar. writeFileSync only sets the
159
200
  // mode on create, so a snapshot left world-readable by an older version is
@@ -167,14 +208,19 @@ export function saveSession(name, state) {
167
208
  * Drop a saved page. `oc logout` calls this alongside clearing the cookie jar:
168
209
  * a snapshot taken under a login holds that page's text, so leaving it behind
169
210
  * would make logout mean "the cookies are gone" rather than "nothing of this
170
- * login remains".
211
+ * login remains". Only a missing file is fine to ignore: a permission error
212
+ * or a name that is a directory leaves the page on disk, and the caller is
213
+ * about to tell the user it is gone.
171
214
  * @param {string} name
215
+ * @returns {boolean} whether a saved page was removed
172
216
  */
173
217
  export function clearSession(name) {
174
218
  try {
175
219
  unlinkSync(sessionPath(name));
176
- } catch {
177
- // nothing saved under that name is fine
220
+ return true;
221
+ } catch (err) {
222
+ if (err?.code === 'ENOENT') return false;
223
+ throw err;
178
224
  }
179
225
  }
180
226
 
@@ -191,3 +237,43 @@ export function loadSession(name) {
191
237
  return null;
192
238
  }
193
239
  }
240
+
241
+ /**
242
+ * Every session on disk, for `oc session ls`: a name is a session when it has
243
+ * a saved page, a cookie jar, or both, since `oc login` creates a jar without
244
+ * a page and that credential is exactly what an agent auditing leftover logins
245
+ * needs to see. An unreadable page is still listed by name: `oc session rm`
246
+ * can drop it. Only names oc itself could have written are listed, so a stray
247
+ * `..json` or a directory named like a page never shows up as something rm
248
+ * then cannot remove.
249
+ * @returns {{name: string, url: string|null, title: string|null, savedAt: string|null, cookies: boolean}[]}
250
+ */
251
+ export function listSessions() {
252
+ let entries;
253
+ try {
254
+ entries = readdirSync(sessionDir(), { withFileTypes: true });
255
+ } catch {
256
+ return [];
257
+ }
258
+ /** @type {Map<string, {name: string, url: string|null, title: string|null, savedAt: string|null, cookies: boolean}>} */
259
+ const byName = new Map();
260
+ const entry = (name) => {
261
+ if (!byName.has(name)) byName.set(name, { name, url: null, title: null, savedAt: null, cookies: false });
262
+ return byName.get(name);
263
+ };
264
+ for (const file of entries) {
265
+ if (!file.isFile()) continue;
266
+ const jarName = file.name.endsWith(COOKIE_JAR_SUFFIX) ? file.name.slice(0, -COOKIE_JAR_SUFFIX.length) : null;
267
+ const pageName = jarName == null && file.name.endsWith('.json') ? file.name.slice(0, -'.json'.length) : null;
268
+ if (jarName != null && isSafeName(jarName)) {
269
+ entry(jarName).cookies = true;
270
+ } else if (pageName != null && isSafeName(pageName)) {
271
+ const info = entry(pageName);
272
+ const state = loadSession(pageName);
273
+ info.url = state?.url ?? null;
274
+ info.title = state?.title ?? null;
275
+ info.savedAt = state?.savedAt ?? null;
276
+ }
277
+ }
278
+ return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
279
+ }