@only-cli/oc 0.5.6 → 0.5.8

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
@@ -29,6 +29,8 @@ npm install -g @only-cli/oc
29
29
 
30
30
  Requires Node 20+. Requests impersonate Chrome via [impers](https://github.com/lexiforest/impers). When a site, or the local copy of libcurl-impersonate, refuses the Chrome identity, the request downgrades to Firefox, and to native fetch when impers is unavailable or refuses both.
31
31
 
32
+ Red Hat OpenShift also installs an `oc`, and both define `login` and `logout` with unrelated meanings, so whichever lands first on `PATH` shadows the other. If you use OpenShift, call this one with `npx @only-cli/oc` instead of installing it globally, or alias the global install to another name.
33
+
32
34
  ### Agent skill
33
35
 
34
36
  Install the [web-browsing-cli skill](https://www.skills.sh/only-cli/oc/web-browsing-cli) for Claude Code, Cursor, Codex, Copilot, and other compatible agents:
@@ -139,7 +141,7 @@ Copy the `Cookie` header from your browser's devtools (Application → Cookies,
139
141
 
140
142
  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.
141
143
 
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.
144
+ Cookies live in a separate sidecar file (`<session>.cookies.json`) under `~/.only-cli/sessions/`, owner-only (mode `0600` in a `0700` directory, 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.
143
145
 
144
146
  `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.
145
147
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@only-cli/oc",
3
- "version": "0.5.6",
3
+ "version": "0.5.8",
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.6 open <url> compact view, numbered elements
12
- npx --yes @only-cli/oc@0.5.6 do <n> follow link [n], or read it if [n] is text
13
- npx --yes @only-cli/oc@0.5.6 find <query> where a string appears, or that place itself
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
14
14
  when only one matches
15
- npx --yes @only-cli/oc@0.5.6 next next ~500 tokens of the page already open
16
- npx --yes @only-cli/oc@0.5.6 read <n> full text of region [n]
17
- npx --yes @only-cli/oc@0.5.6 raw [url] whole page as markdown (--html for cleaned HTML)
18
- npx --yes @only-cli/oc@0.5.6 login seed cookies (--cookie, --domain, --expires)
19
- npx --yes @only-cli/oc@0.5.6 logout [session] forget a session: cookies and saved page
20
- npx --yes @only-cli/oc@0.5.6 session ls list saved sessions (name, url, title)
21
- npx --yes @only-cli/oc@0.5.6 session rm [name] forget a saved session: page and cookies
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
22
22
  ```
23
23
 
24
24
  None of these except `open`/`do`/`raw <url>` fetch anything; they replay the page `open` already saved.
package/src/act.js CHANGED
@@ -42,17 +42,31 @@ function requireBlocks(session) {
42
42
  return state;
43
43
  }
44
44
 
45
+ /**
46
+ * The number a handle was printed as. The compact view writes `[2]`, and
47
+ * agents copy that form into `oc do [2]` / `oc read [2]`. Number('[2]') is
48
+ * NaN, so the printed form used to fail the usage check.
49
+ * @param {unknown} value
50
+ * @returns {number}
51
+ */
52
+ export function parseHandle(value) {
53
+ const s = String(value ?? '').trim();
54
+ const m = /^\[(\d+)\]$/.exec(s) || /^(\d+)$/.exec(s);
55
+ return m ? Number(m[1]) : NaN;
56
+ }
57
+
45
58
  /**
46
59
  * Resolve a numbered handle from the last render into something to open.
47
60
  * Returns the target URL; the caller fetches and renders it exactly as
48
61
  * `oc open` would, so `do` and `open` always agree on what a page looks like.
49
62
  * When the number is text rather than a link it returns `{read}` instead, and
50
63
  * the caller reads it.
51
- * @param {number} n
64
+ * @param {unknown} n
52
65
  * @param {{session?: string}} [opts]
53
66
  * @returns {{url?: string, read?: number, text: string}}
54
67
  */
55
68
  export function activate(n, { session = DEFAULT_SESSION } = {}) {
69
+ n = parseHandle(n);
56
70
  if (!Number.isInteger(n) || n < 1) {
57
71
  throw new Error('usage: oc do <n>, where <n> is a number from the last page');
58
72
  }
@@ -67,7 +81,8 @@ export function activate(n, { session = DEFAULT_SESSION } = {}) {
67
81
  // and opening it is what `do` was asked for. Reading the title back instead
68
82
  // cost a turn, and then another to find the number that does navigate, so a
69
83
  // heading that has an href falls through to the link below.
70
- if ((handle.type === 'text' || handle.type === 'heading') && !handle.href) {
84
+ // A link with no href, a fragment or mailto:, has nothing to fetch either.
85
+ if (['text', 'heading', 'link'].includes(handle.type) && !handle.href) {
71
86
  // There is nothing to follow, but the agent asked to see what is at [n],
72
87
  // and that is what read prints. Refusing would spend a whole turn to name
73
88
  // the command that should have run, and a turn costs more than the page.
@@ -100,6 +115,7 @@ const TRAIL = 6;
100
115
  * @returns {string}
101
116
  */
102
117
  export function read(n, { session = DEFAULT_SESSION, budget = 2000 } = {}) {
118
+ n = parseHandle(n);
103
119
  if (!Number.isInteger(n) || n < 1) {
104
120
  throw new Error('usage: oc read <n>, where <n> is a number from the last page');
105
121
  }
@@ -230,7 +246,7 @@ export function find(query, { session = DEFAULT_SESSION, budget = 500 } = {}) {
230
246
  // the example it names was in the block after it.
231
247
  if (hits.length === 1 && hits[0].n != null) {
232
248
  const only = hits[0];
233
- const follow = only.type === 'link' ? 'do <n> | ' : '';
249
+ const follow = only.href ? 'do <n> | ' : '';
234
250
  return [
235
251
  `1 match for "${query}"${separately}, region [${only.n}]`,
236
252
  read(only.n, { session, budget: budget * FINISH }),
@@ -258,7 +274,7 @@ export function find(query, { session = DEFAULT_SESSION, budget = 500 } = {}) {
258
274
  if (spent + cost > cap && shown) break;
259
275
  spent += cost;
260
276
  shown++;
261
- if (hit.type === 'link') hasLinks = true;
277
+ if (hit.href) hasLinks = true;
262
278
  lines.push(line);
263
279
  }
264
280
  if (shown < hits.length) {
@@ -298,7 +314,7 @@ function search(blocks, terms) {
298
314
  // are read rather than indexed: the whole-match mode above, and `read`.
299
315
  const window = block.text.slice(start, end).replace(/\n/g, ' ');
300
316
  const snippet = `${start > 0 ? '... ' : ''}${window}${end < block.text.length ? ' ...' : ''}`;
301
- out.push({ n, type: block.type, snippet, text: block.text });
317
+ out.push({ n, type: block.type, snippet, text: block.text, href: block.href });
302
318
  }
303
319
  return out;
304
320
  }
package/src/cli.js CHANGED
@@ -237,7 +237,7 @@ async function main() {
237
237
  // view's footer offers when it has cut something.
238
238
  let url;
239
239
  if (command === 'do') {
240
- const target = act.activate(Number(args[0]), { session: sessionName });
240
+ const target = act.activate(args[0], { session: sessionName });
241
241
  // A number that points at text has no page behind it, so `do` reads it
242
242
  // rather than making the agent pay for a second command to be told.
243
243
  if (target.read != null) {
@@ -369,7 +369,7 @@ async function main() {
369
369
  }
370
370
  return;
371
371
  }
372
- case 'read': return console.log(act.read(Number(args[0]), { session: sessionName, budget: asked || 2000 }));
372
+ case 'read': return console.log(act.read(args[0], { session: sessionName, budget: asked || 2000 }));
373
373
  case 'next': return console.log(act.next({ session: sessionName, budget: asked || 500 }));
374
374
  case 'find': return console.log(act.find(args.join(' '), { session: sessionName, budget: asked || 500 }));
375
375
  case 'fill': return act.fill(Number(args[0]), args.slice(1).join(' '));
package/src/cookies.js CHANGED
@@ -411,6 +411,38 @@ export function withheldForScheme(jar, urlStr) {
411
411
  return jar.cookies.some((c) => c.secure && scopeMatches(c, jar, host, path));
412
412
  }
413
413
 
414
+ /**
415
+ * An ISO timestamp, or undefined when the instant is outside what Date can
416
+ * name. A huge Max-Age used to throw RangeError from toISOString and abort
417
+ * the render of a page that was otherwise fine.
418
+ * @param {number} ms
419
+ * @returns {string | undefined}
420
+ */
421
+ function expiryISO(ms) {
422
+ try {
423
+ return new Date(ms).toISOString();
424
+ } catch {
425
+ return undefined;
426
+ }
427
+ }
428
+
429
+ /**
430
+ * Strip one pair of wrapping double quotes from a Path. ASP.NET and several
431
+ * Java containers send Path="/admin"; storing the quotes left pathMatches
432
+ * matching nothing, so the cookie was silently never sent again and the login
433
+ * looked gone on the page it was scoped to.
434
+ *
435
+ * Only Path gets this. A cookie value is stored and echoed back verbatim, as
436
+ * RFC 6265 5.2 and every browser have it, as jarFromCookieHeader already
437
+ * treats a seeded one, and because quoting is how a server protects a value
438
+ * holding a space or a comma.
439
+ * @param {string} s
440
+ * @returns {string}
441
+ */
442
+ function unquotePath(s) {
443
+ return s.length >= 2 && s.startsWith('"') && s.endsWith('"') ? s.slice(1, -1) : s;
444
+ }
445
+
414
446
  /**
415
447
  * Parse one Set-Cookie header value.
416
448
  * @param {string} header
@@ -444,6 +476,16 @@ export function parseSetCookie(header, requestUrl) {
444
476
  ...(url.protocol === 'https:' ? { secure: true } : {}),
445
477
  };
446
478
 
479
+ // Max-Age and Expires are collected separately: RFC 6265 5.3 says Max-Age
480
+ // wins even when Expires is written last. Express writes them in that order,
481
+ // and Expires is the server's clock, so a host whose clock is behind would
482
+ // otherwise look expired the moment it was set.
483
+ /** @type {string | undefined} */
484
+ let maxAgeExpires;
485
+ let sawMaxAge = false;
486
+ /** @type {string | undefined} */
487
+ let expiresAt;
488
+
447
489
  for (const attr of parts.slice(1)) {
448
490
  const sep = attr.indexOf('=');
449
491
  const key = (sep === -1 ? attr : attr.slice(0, sep)).trim().toLowerCase();
@@ -455,7 +497,7 @@ export function parseSetCookie(header, requestUrl) {
455
497
  // dependency this project will not take. User-seeded cookies still scope by
456
498
  // the --domain they pass, which normalizeDomain holds to the same floor.
457
499
  if (key === 'path') {
458
- cookie.path = val || '/';
500
+ cookie.path = unquotePath(val) || '/';
459
501
  } else if (key === 'secure') {
460
502
  cookie.secure = true;
461
503
  } else if (key === 'httponly') {
@@ -463,13 +505,19 @@ export function parseSetCookie(header, requestUrl) {
463
505
  } else if (key === 'max-age') {
464
506
  const age = Number(val);
465
507
  if (Number.isFinite(age)) {
466
- cookie.expires = new Date(Date.now() + age * 1000).toISOString();
508
+ sawMaxAge = true;
509
+ maxAgeExpires = age <= 0 ? new Date(0).toISOString() : expiryISO(Date.now() + age * 1000);
467
510
  }
468
511
  } else if (key === 'expires') {
469
512
  const exp = Date.parse(val);
470
- if (!Number.isNaN(exp)) cookie.expires = new Date(exp).toISOString();
513
+ if (!Number.isNaN(exp)) expiresAt = expiryISO(exp);
471
514
  }
472
515
  }
516
+ if (sawMaxAge) {
517
+ if (maxAgeExpires) cookie.expires = maxAgeExpires;
518
+ } else if (expiresAt) {
519
+ cookie.expires = expiresAt;
520
+ }
473
521
  return cookie;
474
522
  }
475
523
 
package/src/distill.js CHANGED
@@ -119,19 +119,46 @@ const asHTML = (text, url = '', opts = {}) =>
119
119
  * Every heading in the Rust book and every one on an AWS CLI reference page
120
120
  * carries a permalink to its own id, so following those would refetch the
121
121
  * page the agent is already reading, which is worse than the reading it
122
- * already gets. A bare fragment is never a destination.
122
+ * already gets. A bare fragment is never a destination, and neither is a
123
+ * mailto: or tel: href, which is not a page.
123
124
  * @param {any} node - the heading element
124
125
  * @param {string} text - its cleaned text
126
+ * @param {string} base - document base, to resolve the href
127
+ * @param {string} pageUrl - the page itself, for same-document checks
125
128
  * @returns {string|null}
126
129
  */
127
- function headingHref(node, text) {
130
+ function headingHref(node, text, base, pageUrl) {
128
131
  const anchors = node.querySelectorAll('a[href]');
129
132
  if (anchors.length !== 1) return null;
130
133
  const href = anchors[0].getAttribute('href') ?? '';
131
- if (!href || href.startsWith('#')) return null;
134
+ if (!href || !isFollowableHref(href, base, pageUrl)) return null;
132
135
  return clean(anchors[0].textContent) === text ? href : null;
133
136
  }
134
137
 
138
+ /**
139
+ * Whether this href is a page oc can fetch, other than the one already open.
140
+ * A bare fragment is the current page. mailto:/tel:/javascript: are not
141
+ * pages: fetchPage prefixes https:// onto a URL with no http(s) scheme, so
142
+ * mailto:hi@example.com became a GET of example.com with password "hi".
143
+ * The href resolves against <base href>, but "here" is the page URL: under
144
+ * <base href="/">, a link to / is the home page, not this one.
145
+ * @param {string} href
146
+ * @param {string} base
147
+ * @param {string} pageUrl
148
+ * @returns {boolean}
149
+ */
150
+ function isFollowableHref(href, base, pageUrl) {
151
+ try {
152
+ const dest = new URL(href, base || pageUrl || undefined);
153
+ if (!/^https?:$/i.test(dest.protocol)) return false;
154
+ if (!pageUrl) return true;
155
+ const here = new URL(pageUrl);
156
+ return dest.origin !== here.origin || dest.pathname !== here.pathname || dest.search !== here.search;
157
+ } catch {
158
+ return false;
159
+ }
160
+ }
161
+
135
162
  /**
136
163
  * Reduce raw HTML to an interaction tree: readable text plus numbered
137
164
  * elements, in document order. The walk is deterministic and numbering is a
@@ -217,12 +244,19 @@ export function distill(html, url = '') {
217
244
  if (/^h[1-6]$/.test(tag)) {
218
245
  const text = clean(node.textContent);
219
246
  if (text) {
220
- const href = headingHref(node, text);
247
+ const href = headingHref(node, text, base, url);
221
248
  blocks.push({ type: 'heading', level: Number(tag[1]), text, ...(href ? { href } : {}) });
222
249
  }
223
250
  return;
224
251
  }
225
252
  if (tag === 'a' && node.getAttribute('href')) {
253
+ // Same rule as headingHref: a fragment is this page, mailto: is not a
254
+ // page. The link keeps its number without the href, because a fragment
255
+ // is often the one handle on a place: rdoc's method signature links to
256
+ // its own id, and as plain text find borrowed the number above it,
257
+ // which read then opened on the method before.
258
+ const raw = node.getAttribute('href');
259
+ const href = isFollowableHref(raw, base, url) ? raw : null;
226
260
  // An icon button already takes aria-label or title because it has no
227
261
  // text. An anchor around an image is the same shape: img alt is the
228
262
  // accessible name and is not a text node, so textContent is empty and
@@ -233,12 +267,16 @@ export function distill(html, url = '') {
233
267
  || clean(node.getAttribute('title') ?? '')
234
268
  || clean(node.querySelector('img')?.getAttribute('alt') ?? '');
235
269
  if (text) {
236
- blocks.push({ type: 'link', text, href: node.getAttribute('href') });
270
+ blocks.push({ type: 'link', text, ...(href ? { href } : {}) });
237
271
  }
238
272
  return;
239
273
  }
240
274
  if (tag === 'input' || tag === 'textarea' || tag === 'select') {
241
- const kind = node.getAttribute('type') ?? 'text';
275
+ // HTML's type attribute is ASCII case-insensitive. type=HIDDEN used to
276
+ // appear as a numbered input, type=SUBMIT as an input rather than a
277
+ // button, and type=PASSWORD as a field named PASSWORD, so a login wall
278
+ // written that way was not detected.
279
+ const kind = (node.getAttribute('type') ?? 'text').toLowerCase();
242
280
  if (kind === 'hidden') return;
243
281
  if (kind === 'submit' || kind === 'button') {
244
282
  blocks.push({ type: 'button', text: node.getAttribute('value') ?? 'submit' });
@@ -465,7 +503,10 @@ function cleanDocument(html, url = '') {
465
503
  for (const tag of DROP) {
466
504
  for (const el of [...document.querySelectorAll(tag)]) el.remove();
467
505
  }
468
- for (const el of [...document.querySelectorAll('[hidden], [aria-hidden="true"], input[type="hidden"]')]) el.remove();
506
+ for (const el of [...document.querySelectorAll('[hidden], [aria-hidden="true"]')]) el.remove();
507
+ for (const el of [...document.querySelectorAll('input')]) {
508
+ if ((el.getAttribute('type') ?? '').toLowerCase() === 'hidden') el.remove();
509
+ }
469
510
  for (const el of [...document.querySelectorAll('[style]')]) {
470
511
  if (/display:\s*none/.test(el.getAttribute('style') ?? '')) el.remove();
471
512
  }
package/src/render.js CHANGED
@@ -127,7 +127,10 @@ export function render(page, { budget = 500, from = 0 } = {}) {
127
127
  if (spent + cost > limit && lines.length > head.length) break;
128
128
  spent += cost;
129
129
  lines.push(line);
130
- if (block.type === 'link' || block.type === 'button') hasLinks = true;
130
+ // A heading that is a link (search result titles) is what do follows, so
131
+ // it has to count here or the footer omits do on a page of only those. A
132
+ // link with no href is a fragment or mailto:, which do only reads.
133
+ if (block.type === 'button' || block.href) hasLinks = true;
131
134
  }
132
135
 
133
136
  const rest = blocks.slice(i);
package/src/session.js CHANGED
@@ -104,16 +104,29 @@ function unwrapRedirect(url) {
104
104
 
105
105
  /**
106
106
  * Absolute URL for a handle, or null when the link is not followable
107
- * (javascript: handlers, malformed hrefs).
107
+ * (javascript: handlers, mailto:/tel:, same-document fragments, malformed
108
+ * hrefs). fetchPage prefixes https:// onto anything that is not already
109
+ * http(s), so mailto:hi@example.com used to become a GET of example.com
110
+ * with password "hi". A bare fragment is the page already open.
108
111
  * @param {string} href
109
- * @param {string} base
112
+ * @param {string} base - <base href>, or the page URL when it set none
113
+ * @param {string} [pageUrl] - the page itself, for same-document checks
110
114
  * @returns {string|null}
111
115
  */
112
- export function resolveHref(href, base) {
113
- if (!href || /^(javascript|about):/i.test(href)) return null;
116
+ export function resolveHref(href, base, pageUrl = base) {
117
+ if (!href) return null;
114
118
  try {
115
119
  const url = new URL(href, base || undefined);
116
- return unwrapRedirect(url) ?? url.href;
120
+ if (!/^https?:$/i.test(url.protocol)) return null;
121
+ const dest = unwrapRedirect(url) ?? url.href;
122
+ if (pageUrl) {
123
+ const here = new URL(pageUrl);
124
+ const there = new URL(dest);
125
+ if (here.origin === there.origin && here.pathname === there.pathname && here.search === there.search) {
126
+ return null;
127
+ }
128
+ }
129
+ return dest;
117
130
  } catch {
118
131
  return null;
119
132
  }
@@ -145,7 +158,7 @@ export function sessionFromPage(page, previous, { cursor = 0 } = {}) {
145
158
  continue;
146
159
  }
147
160
  // Relative hrefs are against <base href> when the page set one.
148
- const href = block.href ? resolveHref(block.href, page.base || page.url) : null;
161
+ const href = block.href ? resolveHref(block.href, page.base || page.url, page.url) : null;
149
162
  blocks.push({
150
163
  type: block.type,
151
164
  text: block.text,