@only-cli/oc 0.2.0-beta.1 → 0.3.0-beta.1

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/src/cli.js CHANGED
@@ -4,30 +4,55 @@ import { fetchPage } from './fetch.js';
4
4
  import { distill, toMarkdown, toHTML } from './distill.js';
5
5
  import { render, estimateTokens } from './render.js';
6
6
  import * as act from './act.js';
7
+ import { DEFAULT_SESSION, loadSession, saveSession, sessionFromPage } from './session.js';
7
8
 
8
9
  const HELP = `only-cli: the web as a compact terminal, built for AI agents.
9
10
 
10
11
  usage: oc <command> [args] [flags]
11
12
 
12
13
  open <url> fetch and render a page with numbered actions
13
- raw <url> distilled markdown of the whole page
14
- do <n> activate a numbered element (v0.2)
15
- fill <n> <text> type into a numbered input (v0.2)
16
- submit [n] submit a form (v0.2)
17
- read [n] full text of one region (v0.2)
18
- find <query> search visible text on the current page (v0.2)
19
- back | next history and pagination (v0.2)
20
- session ls|rm manage saved sessions (v0.2)
14
+ find <query> where a string appears on the page already open
15
+ next the next budget worth of the page already open
16
+ read <n> full text of the region at [n], up to 2000 tokens
17
+ raw [url] distilled markdown of the whole page
18
+ do <n> follow the numbered link [n], or read [n] if it is text
19
+ fill <n> <text> type into a numbered input (planned)
20
+ submit [n] submit a form (planned)
21
+ back return to the previous page (planned)
22
+ session ls|rm manage saved sessions (planned)
21
23
 
22
24
  flags:
23
- --budget <tokens> tighten or loosen the render budget (default 500)
25
+ --budget <tokens> tighten or loosen the render budget (default 500,
26
+ 2000 for read). It is a target, not a ceiling: a page
27
+ that would finish within about four times it is printed
28
+ whole rather than costing you a second command
24
29
  --json machine-stable JSON output
25
30
  --html raw only: cleaned HTML instead of markdown
26
31
  --verbose, -v metrics on stderr: tokens saved vs the page HTML, HTTP
27
32
  status and client identity, timing, transfer size, and
28
33
  memory. --stats is an alias; OC_VERBOSE=1 turns it on
29
34
  globally. Off by default because metrics cost tokens too.
30
- --session <name> named session (v0.2)`;
35
+ --session <name> keep separate page state under a name (default: default)
36
+
37
+ 'oc open' remembers the page it printed, so 'oc do 3' follows link [3] without
38
+ you ever handling its URL, and 'oc next' or 'oc read 12' picks up what the
39
+ budget left behind without fetching it again. State lives in ~/.only-cli
40
+ (override with OC_HOME).`;
41
+
42
+ // A rendered page has to be remembered or its [3] means nothing to the next
43
+ // command. Saving state must never break a render, so a home directory that
44
+ // cannot be written costs the agent `do`, `read`, and `next`, and nothing
45
+ // else, but silently: a sandbox that blocks the write leaves `do` resolving
46
+ // against whatever session last saved successfully, possibly from an
47
+ // unrelated page, with no sign anything is wrong. So the failure still prints,
48
+ // on stderr where it costs nothing until something breaks.
49
+ const remember = (page, name, cursor) => {
50
+ try {
51
+ saveSession(name, sessionFromPage(page, loadSession(name), { cursor }));
52
+ } catch (err) {
53
+ console.error(`oc: warning: could not save session '${name}' (${err.message}), 'do'/'read'/'next' may act on stale state`);
54
+ }
55
+ };
31
56
 
32
57
  // What browsing costs without this tool is the raw page HTML in context.
33
58
  const savings = (out, raw) =>
@@ -57,13 +82,36 @@ async function main() {
57
82
  return;
58
83
  }
59
84
 
85
+ const sessionName = values.session || DEFAULT_SESSION;
86
+ // Zero means "whatever this command's default is", which differs: the
87
+ // compact view targets 500 tokens, read targets 2000.
88
+ const asked = values.budget ? Number(values.budget) : 0;
89
+ if (values.budget && (!Number.isFinite(asked) || asked <= 0)) {
90
+ throw new Error('--budget must be a positive number');
91
+ }
92
+
60
93
  switch (command) {
61
94
  case 'open':
95
+ case 'do':
62
96
  case 'raw': {
63
- const url = args[0];
97
+ // `do` is `open` with the URL looked up from the last render instead of
98
+ // typed, so both commands share one fetch, render, and save path. `raw`
99
+ // with no URL means the page already open, which is what the compact
100
+ // view's footer offers when it has cut something.
101
+ let url;
102
+ if (command === 'do') {
103
+ const target = act.activate(Number(args[0]), { session: sessionName });
104
+ // A number that points at text has no page behind it, so `do` reads it
105
+ // rather than making the agent pay for a second command to be told.
106
+ if (target.read != null) {
107
+ return console.log(act.read(target.read, { session: sessionName, budget: asked || 2000 }));
108
+ }
109
+ url = target.url;
110
+ } else {
111
+ url = args[0] ?? (command === 'raw' ? loadSession(sessionName)?.url : undefined);
112
+ }
64
113
  if (!url) throw new Error(`usage: oc ${command} <url>`);
65
- const budget = values.budget ? Number(values.budget) : 500;
66
- if (!Number.isFinite(budget) || budget <= 0) throw new Error('--budget must be a positive number');
114
+ const budget = asked || 500;
67
115
  const t0 = performance.now();
68
116
  const { url: finalUrl, html, status, via } = await fetchPage(url);
69
117
  const fetchMs = performance.now() - t0;
@@ -74,32 +122,34 @@ async function main() {
74
122
  + `${Math.round(html.length / 1024)}KB transferred, ${Math.round(rss / 1048576)}MB memory`;
75
123
  };
76
124
  if (values.json) {
77
- console.log(JSON.stringify(distill(html, finalUrl)));
125
+ const page = distill(html, finalUrl);
126
+ remember(page, sessionName);
127
+ console.log(JSON.stringify(page));
78
128
  if (verbose) console.error(resources());
79
129
  return;
80
130
  }
81
131
  const htmlTokens = estimateTokens(html);
82
132
  if (command === 'raw') {
83
- const out = values.html ? toHTML(html) : toMarkdown(html);
133
+ const out = values.html ? toHTML(html, finalUrl) : toMarkdown(html, finalUrl);
84
134
  console.log(out);
85
135
  if (verbose) console.error(`${savings(estimateTokens(out), htmlTokens)}; ${resources()}`);
86
136
  return;
87
137
  }
88
138
  const page = distill(html, finalUrl);
89
139
  const { text, stats } = render(page, { budget });
140
+ remember(page, sessionName, stats.next);
90
141
  console.log(text);
91
142
  if (verbose) {
92
143
  console.error(`~${stats.tokens} tokens, ${stats.rendered}/${stats.blocks} blocks rendered, ${savings(stats.tokens, htmlTokens)}; ${resources()}`);
93
144
  }
94
145
  return;
95
146
  }
96
- case 'do': return act.activate(Number(args[0]));
147
+ case 'read': return console.log(act.read(Number(args[0]), { session: sessionName, budget: asked || 2000 }));
148
+ case 'next': return console.log(act.next({ session: sessionName, budget: asked || 500 }));
149
+ case 'find': return console.log(act.find(args.join(' '), { session: sessionName, budget: asked || 500 }));
97
150
  case 'fill': return act.fill(Number(args[0]), args.slice(1).join(' '));
98
151
  case 'submit': return act.submit(args[0] ? Number(args[0]) : undefined);
99
- case 'read': return act.read(args[0] ? Number(args[0]) : undefined);
100
- case 'find': return act.find(args.join(' '));
101
152
  case 'back': return act.back();
102
- case 'next': return act.next();
103
153
  case 'session': throw new act.NotImplemented('session');
104
154
  default:
105
155
  throw new Error(`unknown command '${command}', run oc --help`);