opencode-moli 0.0.0-stage → 3.1.0

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.
@@ -0,0 +1,1001 @@
1
+ /**
2
+ * Moli runner: spawn the local `moli.exe` headless-browser engine and return its
3
+ * output without the two traps this machine hits.
4
+ *
5
+ * Trap 1 — pipe capture. Under DSH's Windows sandbox a child process cannot open
6
+ * inherited named pipes, so `spawnSync(..., { stdio: 'pipe' })` yields status
7
+ * `null` and zero bytes. Output therefore always goes to real files and is read
8
+ * back afterwards.
9
+ *
10
+ * Trap 2 — UTF-16 mangling. PowerShell's `>` operator re-encodes a native
11
+ * program's bytes, so a screenshot written that way grows a `00` after every
12
+ * byte and is no longer a PNG. Bytes are copied verbatim from the file here.
13
+ *
14
+ * @module dsh-moli/lib/moli
15
+ */
16
+ import { spawnSync } from 'node:child_process';
17
+ import { createHash } from 'node:crypto';
18
+ import { closeSync, existsSync, mkdtempSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
19
+ import { homedir, tmpdir } from 'node:os';
20
+ import { dirname, join } from 'node:path';
21
+
22
+ /** Output formats that are bytes, not text. */
23
+ const BINARY_DUMPS = new Set(['screenshot', 'screenshot_full', 'pdf']);
24
+
25
+ /** Formats that require the layout renderer to produce anything at all. */
26
+ const LAYOUT_DUMPS = new Set(['screenshot', 'screenshot_full', 'pdf']);
27
+
28
+ /** Formats whose output is a self-describing text document. */
29
+ const TEXT_DUMPS = new Set([undefined, 'html', 'markdown', 'json', 'semantic_tree', 'semantic_tree_text']);
30
+
31
+ /** Accepted `--wait` lifecycle stages. */
32
+ const WAIT_STAGES = new Set(['domcontentloaded', 'load', 'networkidle', 'domstable', 'done']);
33
+
34
+ /**
35
+ * The exit code the engine uses for "the final main-document status was >= 400".
36
+ * Its help states it for `--fail` and `--fail-with-body`; treating it specially is
37
+ * what lets an HTTP error be reported without discarding the body.
38
+ */
39
+ const ENGINE_HTTP_ERROR_STATUS = 22;
40
+
41
+ /** `scroll` keywords, mapped to what they mean in the page. */
42
+ const SCROLL_TOKENS = {
43
+ top: '0',
44
+ bottom: 'document.documentElement.scrollHeight',
45
+ };
46
+
47
+ /**
48
+ * Build the expression that returns the text of the elements a CSS selector matches.
49
+ *
50
+ * This exists because reading one container should not cost the whole page: on a
51
+ * node-dense listing page the full markdown dump measured 95,605 characters while
52
+ * the same page's video cards came to 1,829. `--eval` can already do this, but it
53
+ * requires writing the JavaScript; a selector is the same idea with no syntax to get
54
+ * wrong, which is what a model that is not fluent in the DOM needs.
55
+ *
56
+ * It works within one navigation -- the value is returned by the engine's own
57
+ * evaluation, so the "page is gone by the time the result is assembled" limitation
58
+ * does not apply.
59
+ *
60
+ * The result is prefixed with a machine-readable count, because the engine prints an
61
+ * empty string for an expression that yields `""`, and an empty selection is
62
+ * otherwise indistinguishable from a page with no text. A selector that matches
63
+ * nothing is reported as a failure rather than as empty content: the caller picked a
64
+ * selector that is not on the page, and telling them so is the whole point.
65
+ *
66
+ * @param selector - a CSS selector.
67
+ * @returns a JavaScript expression, or undefined when no selector was given.
68
+ */
69
+ export function selectorScript(selector) {
70
+ if (typeof selector !== 'string' || selector.trim() === '') return undefined;
71
+ // JSON.stringify quotes the selector safely for embedding; a selector is data, not
72
+ // code, and must never be spliced into the expression raw.
73
+ const quoted = JSON.stringify(selector);
74
+ return `(() => {
75
+ const nodes = [...document.querySelectorAll(${quoted})];
76
+ // Fall back to textContent when innerText is EMPTY, not merely absent.
77
+ // \`??\` treats an empty string as a value, so a page whose layout has not been
78
+ // computed for these nodes returned "matched N but none has any text" -- measured
79
+ // on Bing: 10 matched elements, all with an innerText of '' and a textContent of
80
+ // 150-240 characters. That is a wrong failure for a page that reads fine.
81
+ const texts = nodes.map(node => {
82
+ const inner = (node.innerText ?? '').trim();
83
+ return inner !== '' ? inner : (node.textContent ?? '').trim();
84
+ }).filter(text => text !== '');
85
+ return '[dsh-moli:selector]' + JSON.stringify({
86
+ matched: nodes.length,
87
+ withText: texts.length,
88
+ joined: texts.join('\\n'),
89
+ });
90
+ })()`;
91
+ }
92
+
93
+ /**
94
+ * Build the expression that scrolls the page, to be run by the engine's own
95
+ * `--eval` before the dump.
96
+ *
97
+ * Scrolling is not a nicety: a page can load content on its first scroll event, and
98
+ * then a fetch without scrolling sees a placeholder while the same fetch with it
99
+ * sees the content. Verified against a page whose scroll handler fills a slot --
100
+ * the dump carried the loaded text with `scroll` and the placeholder without it.
101
+ * Moli does serialize the whole document either way, so this is not about reaching
102
+ * content that "below the fold" already contains; it is about triggering the
103
+ * handler, the intersection observer, or the lazy image that only runs on a scroll.
104
+ *
105
+ * **The expression must not return the scroll position.** Without `--dump` the
106
+ * engine prints whatever `--eval` evaluates to, so returning `String(window.scrollY)`
107
+ * here replaced the page with the number `600`: `moli_fetch url=... scroll=600`
108
+ * answered `600`, while the identical call without `scroll` returned the document's
109
+ * HTML. The scroll is a side effect; the value it wants to report is recorded on
110
+ * `window` instead, where a later read can pick it up without changing what the
111
+ * engine prints.
112
+ *
113
+ * @param scroll - pixels down (negative scrolls up), or `top` / `bottom`.
114
+ * @returns a JavaScript expression, or undefined when there is nothing to do.
115
+ */
116
+ export function scrollScript(scroll) {
117
+ if (scroll === undefined || scroll === null) return undefined;
118
+ let target;
119
+ if (typeof scroll === 'number') {
120
+ if (!Number.isFinite(scroll)) return undefined;
121
+ target = String(Math.trunc(scroll));
122
+ } else if (typeof scroll === 'string') {
123
+ const key = scroll.trim().toLowerCase();
124
+ if (key === '') return undefined;
125
+ target = SCROLL_TOKENS[key] ?? (/^-?\d+$/u.test(key) ? key : undefined);
126
+ if (target === undefined) return undefined;
127
+ } else {
128
+ return undefined;
129
+ }
130
+ // Dispatch a scroll event as well as moving: `window.scrollTo` updates the
131
+ // position, but a page listening for the event is the reason this exists. The
132
+ // height is captured on both sides of the move so a caller can tell whether the
133
+ // page grew -- which is the one signal that says lazy loading actually happened.
134
+ return `(() => {
135
+ const before = document.body === null ? 0 : document.body.scrollHeight;
136
+ window.scrollTo(0, ${target});
137
+ window.dispatchEvent(new Event('scroll'));
138
+ window.__dshMoliScroll = {
139
+ requested: ${target},
140
+ y: window.scrollY,
141
+ heightBefore: before,
142
+ heightAfter: document.body === null ? 0 : document.body.scrollHeight,
143
+ };
144
+ })()`;
145
+ }
146
+
147
+ /**
148
+ * Build the one expression the engine will run from `scroll`, `selector` and `eval`.
149
+ *
150
+ * The engine accepts a single `--eval`, so everything that has to happen before the
151
+ * page is captured is composed here, in the order the caller expects: scroll first,
152
+ * then read (a selector or the caller's expression).
153
+ *
154
+ * What gets returned depends on whether anything else will produce the output, and
155
+ * getting this wrong breaks the feature in one direction or the other:
156
+ *
157
+ * - **A `dump` was requested.** The dump produces the output, so the expression is
158
+ * there only for its side effects and its value is discarded by the engine anyway.
159
+ * It must still be passed, or the scroll never runs.
160
+ * - **No `dump`.** The expression's value *is* the output, whether it is a selector
161
+ * or the caller's own expression.
162
+ * - **No `dump`, no selector, no caller expression, only `scroll`.** The engine
163
+ * prints whatever `--eval` evaluates to, so passing the scroll expression here
164
+ * would replace the page with the scroll's return value. `undefined` is returned
165
+ * instead, leaving the engine's default output -- the serialized document --
166
+ * intact. This is the case that shipped broken: `moli_fetch url=... scroll=600`
167
+ * answered `600`.
168
+ *
169
+ * @param evalExpression - the caller's expression, if any.
170
+ * @param scroll - the caller's `scroll` value, if any.
171
+ * @param hasDump - whether the caller also asked for a dump.
172
+ * @param selector - the caller's CSS selector, if any.
173
+ * @returns the expression to pass, or undefined to let the engine decide.
174
+ */
175
+ export function combineEval(evalExpression, scroll, hasDump = false, selector = undefined) {
176
+ const move = scrollScript(scroll);
177
+ const read = selectorScript(selector);
178
+ const caller = evalExpression === undefined || evalExpression === '' ? undefined : evalExpression;
179
+
180
+ // A selector is a read, so it replaces the caller's expression rather than being
181
+ // chained with it; `buildArgs` rejects the two together, so only one is ever set.
182
+ // The selector script is already a call expression; a caller's expression has to be
183
+ // wrapped so its value is what the engine reports.
184
+ const body = read !== undefined ? { code: read, wrapped: true } : (caller === undefined ? undefined : { code: caller, wrapped: false });
185
+
186
+ if (move === undefined) return body === undefined ? undefined : body.code;
187
+ if (body === undefined) {
188
+ // No read at all: keep the scroll only when a dump will produce the output.
189
+ return hasDump ? move : undefined;
190
+ }
191
+ // The read goes last so its value is the one the engine reports; losing it would
192
+ // contradict the documented `eval` behaviour.
193
+ return `${move}; ${body.wrapped ? body.code : `(() => (${body.code}))()`}`;
194
+ }
195
+
196
+ /**
197
+ * Every place this plugin will look for `moli.exe`, most explicit first.
198
+ *
199
+ * The recursive `%LOCALAPPDATA%\Moli` entry exists because Moli's installer has
200
+ * placed the binary under versioned subdirectories, so a fixed `bin\moli.exe`
201
+ * path is not enough to find an installation that plainly exists.
202
+ *
203
+ * @param override - explicit path from configuration, when set.
204
+ * @returns candidate paths, in probe order.
205
+ */
206
+ export function moliCandidates(override) {
207
+ const isWin = process.platform === 'win32';
208
+ const home = process.env.HOME ?? homedir();
209
+ const listed = [
210
+ override,
211
+ process.env.MOLI_BIN,
212
+ // Windows: official installer location.
213
+ isWin && process.env.LOCALAPPDATA !== undefined ? join(process.env.LOCALAPPDATA, 'Moli', 'bin', 'moli.exe') : undefined,
214
+ isWin && process.env.USERPROFILE !== undefined ? join(process.env.USERPROFILE, '.local', 'bin', 'moli.exe') : undefined,
215
+ // Linux/macOS: installer.sh default ~/.local/bin/moli, plus versioned/shared dirs.
216
+ !isWin ? join(home, '.local', 'bin', 'moli') : undefined,
217
+ !isWin ? join(home, '.local', 'share', 'moli', 'bin', 'moli') : undefined,
218
+ !isWin ? join(home, '.local', 'share', 'moli', 'moli') : undefined,
219
+ !isWin ? join(home, '.moli', 'bin', 'moli') : undefined,
220
+ ].filter(candidate => typeof candidate === 'string' && candidate.length > 0);
221
+
222
+ const discovered = [];
223
+ if (isWin) {
224
+ const root = process.env.LOCALAPPDATA === undefined ? undefined : join(process.env.LOCALAPPDATA, 'Moli');
225
+ if (root !== undefined && existsSync(root)) {
226
+ let entries = [];
227
+ try {
228
+ entries = readdirSync(root, { recursive: true, withFileTypes: true });
229
+ } catch {
230
+ entries = [];
231
+ }
232
+ for (const entry of entries) {
233
+ if (entry.isFile() && entry.name.toLowerCase() === 'moli.exe') {
234
+ discovered.push(join(entry.parentPath ?? root, entry.name));
235
+ }
236
+ }
237
+ }
238
+ } else {
239
+ const seen = new Set(listed);
240
+ for (const dir of String(process.env.PATH ?? '').split(':')) {
241
+ if (dir === '') continue;
242
+ const candidate = join(dir, 'moli');
243
+ if (existsSync(candidate) && !seen.has(candidate)) discovered.push(candidate);
244
+ }
245
+ }
246
+ return [...listed, ...discovered];
247
+ }
248
+
249
+ /**
250
+ * Locate the installed `moli.exe`.
251
+ *
252
+ * @param override - explicit path from configuration, when set.
253
+ * @returns the absolute executable path, or undefined when nothing exists there.
254
+ */
255
+ export function findMoli(override) {
256
+ for (const candidate of moliCandidates(override)) {
257
+ if (existsSync(candidate)) return candidate;
258
+ }
259
+ return undefined;
260
+ }
261
+
262
+ /**
263
+ * Read moli's version banner.
264
+ *
265
+ * @param exe - absolute path to `moli.exe`.
266
+ * @returns the version string, or undefined when the call failed.
267
+ */
268
+ export function moliVersion(exe) {
269
+ // Via runOnce, not a pipe: the sandbox blocks inherited-pipe capture, which
270
+ // would report "unknown" even for a perfectly good executable.
271
+ const outcome = runOnce({ exe, args: ['--version'] });
272
+ if (outcome.status !== 0) return undefined;
273
+ const text = outcome.stdout.toString('utf8').trim();
274
+ return text === '' ? undefined : text;
275
+ }
276
+
277
+ /**
278
+ * Normalize a diagnostic blob into one readable line.
279
+ *
280
+ * The engine writes "Error: ...\nReason: ..." to stderr; keep the leading lines
281
+ * and drop control bytes so the message survives a JSON round trip.
282
+ *
283
+ * @param text - raw stderr text.
284
+ * @returns the condensed message.
285
+ */
286
+ function condense(text) {
287
+ return String(text)
288
+ .replace(/\u001b\[[0-9;]*m/gu, '')
289
+ .replace(/\r/gu, '')
290
+ .split('\n')
291
+ .map(line => line.trim())
292
+ .filter(line => line.length > 0)
293
+ .slice(0, 6)
294
+ .join(' | ');
295
+ }
296
+
297
+ /**
298
+ * Decide whether a failure is the sandbox's Schannel block rather than a real
299
+ * network fault, so the caller can say so explicitly instead of guessing.
300
+ *
301
+ * @param message - condensed stderr text.
302
+ * @returns whether the low-integrity TLS restriction caused it.
303
+ */
304
+ export function isSandboxTlsFailure(message) {
305
+ return /SEC_E_NO_CREDENTIALS|schannel/iu.test(message);
306
+ }
307
+
308
+ /**
309
+ * Classify a transport failure: did the host never answer, or did a wait condition
310
+ * simply never become true?
311
+ *
312
+ * A blocked host fails at connect time (`Failed to connect`, reset, refused) or,
313
+ * when the socket never opens, as a readiness timeout with nothing to show. A
314
+ * readiness timeout can also mean a genuinely slow page, so that weaker case is
315
+ * reported separately as {@link possiblyUnreachable}.
316
+ *
317
+ * **But not every readiness timeout is about the network.** The engine reports the
318
+ * condition it was waiting for, and three of them mean the page was already there:
319
+ *
320
+ * ... while waiting for a selector
321
+ * ... while waiting for a script to become truthy
322
+ * ... while waiting for a subresource response
323
+ *
324
+ * In those cases the document was fetched and parsed; what did not happen is the
325
+ * selector appearing, the script becoming true, or the matching response arriving.
326
+ * Telling the caller to retry or configure a proxy then sends them to look at their
327
+ * network for a problem that is in their selector -- measured: `waitSelector` on an
328
+ * element that is not on the page used to report "the host did not answer in time".
329
+ * A timeout "while waiting for response headers" is the opposite case and stays
330
+ * classified as possibly unreachable, because that one really is the server.
331
+ *
332
+ * @param message - condensed stderr text.
333
+ * @returns `unreachable` (connect-time), `possiblyUnreachable` (network timeout), and
334
+ * `conditionTimedOut` (a wait that the page itself never satisfied).
335
+ */
336
+ export function isUnreachableFailure(message) {
337
+ const text = String(message);
338
+ const connectFailure = /Failed to connect|Could not connect|Connection was reset|Connection refused/iu.test(text);
339
+ const anyTimeout = /Timeout was reached|readiness timed out/iu.test(text);
340
+ const conditionTimedOut = /readiness timed out .*?while waiting for (?:a selector|a script|a subresource response)/iu.test(text);
341
+ return {
342
+ unreachable: connectFailure,
343
+ // A condition timeout is not evidence about the network: the page arrived. Only
344
+ // the remaining timeouts are worth mentioning as a reachability possibility.
345
+ possiblyUnreachable: connectFailure || (anyTimeout && !conditionTimedOut),
346
+ conditionTimedOut,
347
+ };
348
+ }
349
+
350
+ /**
351
+ * Run one `moli` invocation and return its stdout as bytes plus its stderr as text.
352
+ *
353
+ * @param options - executable path, argv, timeout, and optional proxy.
354
+ * @returns the settled outcome; never throws for a non-zero exit.
355
+ */
356
+ export function runOnce(options) {
357
+ const dir = mkdtempSync(join(tmpdir(), 'dsh-moli-'));
358
+ const outPath = join(dir, 'stdout.bin');
359
+ const errPath = join(dir, 'stderr.txt');
360
+ let outFd;
361
+ let errFd;
362
+ try {
363
+ outFd = openSync(outPath, 'w');
364
+ errFd = openSync(errPath, 'w');
365
+ const spawnArgs = [...options.args];
366
+ if (options.timeoutMs !== undefined) spawnArgs.push('-t', String(options.timeoutMs));
367
+ if (options.proxy !== undefined && options.proxy !== '') {
368
+ spawnArgs.push('--http-proxy', options.proxy);
369
+ }
370
+ const result = spawnSync(options.exe, spawnArgs, {
371
+ stdio: ['ignore', outFd, errFd],
372
+ // Cancellation backstop, not the engine's readiness deadline: it must sit
373
+ // above the `-t` value handed to moli, or the process is killed before it
374
+ // can report its own timeout.
375
+ timeout: options.spawnTimeoutMs ?? (options.timeoutMs === undefined ? 60000 : options.timeoutMs + 30000),
376
+ windowsHide: true,
377
+ });
378
+ closeSync(outFd);
379
+ outFd = undefined;
380
+ closeSync(errFd);
381
+ errFd = undefined;
382
+
383
+ const stdout = existsSync(outPath) ? readFileSync(outPath) : Buffer.alloc(0);
384
+ const stderrText = existsSync(errPath) ? readFileSync(errPath, 'utf8') : '';
385
+ const failed = result.error !== undefined && result.error !== null;
386
+ return {
387
+ status: failed ? null : (result.status ?? 0),
388
+ stdout,
389
+ stderr: condense(stderrText),
390
+ spawnError: failed ? `${result.error.code ?? 'spawn failed'}: ${result.error.message}` : undefined,
391
+ };
392
+ } finally {
393
+ if (outFd !== undefined) closeSync(outFd);
394
+ if (errFd !== undefined) closeSync(errFd);
395
+ rmSync(dir, { recursive: true, force: true });
396
+ }
397
+ }
398
+
399
+ /**
400
+ * Run one `moli fetch` and return its stdout as bytes plus its stderr as text.
401
+ *
402
+ * The timeout is spliced in *before* the caller's options. Appending it would
403
+ * place `-t <ms>` after a trailing `--eval <expression>`, whose option there
404
+ * swallows the value — so `moli … --eval "1+1" -t 30000` would evaluate the
405
+ * timeout instead of the expression.
406
+ *
407
+ * @param options - executable path, argv tail, timeout, and optional proxy.
408
+ * @returns the settled outcome; never throws for a non-zero exit.
409
+ */
410
+ export function fetchOnce(options) {
411
+ const prelude = options.timeoutMs === undefined ? [] : ['-t', String(options.timeoutMs)];
412
+ const argv = options.args.length > 0 && options.args[0] === 'fetch'
413
+ ? [options.args[0], ...prelude, ...options.args.slice(1)]
414
+ : [...options.args, ...prelude];
415
+ return runOnce({
416
+ ...options,
417
+ args: argv,
418
+ timeoutMs: undefined,
419
+ spawnTimeoutMs: options.timeoutMs === undefined ? undefined : options.timeoutMs + 30000,
420
+ });
421
+ }
422
+
423
+ /**
424
+ * Translate one tool argument set into the engine's argv.
425
+ *
426
+ * @param args - validated tool arguments.
427
+ * @returns the argv tail (everything after the executable).
428
+ */
429
+ /**
430
+ * Build the `moli fetch` argument vector for one call.
431
+ *
432
+ * Exported so the mapping from tool parameters to engine flags can be asserted
433
+ * directly. That matters more than it sounds: a parameter that silently fails to
434
+ * reach the engine is indistinguishable from a feature that does not work, and the
435
+ * only fast, deterministic way to tell them apart is to check the vector.
436
+ *
437
+ * @param args - tool arguments.
438
+ * @returns the argv tail (without the executable).
439
+ */
440
+ export function buildArgs(args) {
441
+ if (args.dump !== undefined && !TEXT_DUMPS.has(args.dump) && !BINARY_DUMPS.has(args.dump)) {
442
+ throw new Error(`unsupported dump: ${String(args.dump)}`);
443
+ }
444
+ if (args.wait !== undefined && args.wait !== '' && !WAIT_STAGES.has(args.wait)) {
445
+ throw new Error(`unsupported wait stage: ${String(args.wait)}`);
446
+ }
447
+ const needsLayout = LAYOUT_DUMPS.has(args.dump) || args.layout === true || args.scrollbars === true;
448
+ // The URL is caller input and goes LAST, after `--`. Without the separator a URL
449
+ // beginning with `-` is read as an option: `moli fetch --https-proxy=...` answers
450
+ // "unexpected argument", and a crafted value could set a flag the caller never
451
+ // asked for. The engine says as much in its own error ("to pass '--not-a-flag' as
452
+ // a value, use '-- --not-a-flag'"). Flags therefore have to be pushed first and the
453
+ // positional argument appended at the end, which is why the URL is not argv[1].
454
+ const argv = ['fetch'];
455
+
456
+ if (args.dump !== undefined) argv.push('-d', args.dump);
457
+ // Screenshots and PDFs silently produce nothing without the layout renderer.
458
+ if (needsLayout) argv.push('--layout');
459
+ if (args.scrollbars === true) argv.push('--scrollbars');
460
+ // `scroll` and `selector` ride along in the same expression: the engine takes a
461
+ // single `--eval`. `hasDump` matters -- see combineEval -- because with a dump the
462
+ // expression exists only for its side effect, and without one it becomes the output.
463
+ const evaluation = combineEval(args.eval, args.scroll, args.dump !== undefined, args.selector);
464
+ if (evaluation !== undefined) argv.push('--eval', evaluation);
465
+ if (args.wait !== undefined && args.wait !== '') argv.push('--wait', args.wait);
466
+ if (args.waitSelector !== undefined && args.waitSelector !== '') argv.push('--wait-selector', args.waitSelector);
467
+ if (args.waitScript !== undefined && args.waitScript !== '') argv.push('--wait-script', args.waitScript);
468
+ // Response waits: the right way to await an AJAX list, where a fixed delay is a
469
+ // guess. The engine takes one of each, and a caller supplying several is asking
470
+ // for "any of these", which is the engine's own semantics for multiple waits.
471
+ if (args.waitResponseUrl !== undefined && args.waitResponseUrl !== '') argv.push('--wait-response-url', args.waitResponseUrl);
472
+ if (args.waitResponseJson !== undefined && args.waitResponseJson !== '') argv.push('--wait-response-json', args.waitResponseJson);
473
+ // The engine's own switch, but only when the caller asked for a failure to be
474
+ // surfaced: adding it unconditionally would turn every 404 into `ok: false` and
475
+ // change what existing calls do.
476
+ if (args.failOnHttpError === true) argv.push('--fail-with-body');
477
+ if (args.delayMs !== undefined) argv.push('--delay-ms', String(args.delayMs));
478
+ if (args.noJs === true) argv.push('--disable-js');
479
+ if (args.noCss === true) argv.push('--disable-css');
480
+ if (args.resources === true) argv.push('--resource');
481
+ if (args.withFrames === true) argv.push('--with-frames');
482
+ if (args.insecureTls === true) argv.push('--insecure-disable-tls-host-verification');
483
+ if (args.userAgent !== undefined && args.userAgent !== '') argv.push('--user-agent', args.userAgent);
484
+ if (args.profileDir !== undefined && args.profileDir !== '') argv.push('--profile-dir', args.profileDir);
485
+ if (args.cookieFile !== undefined && args.cookieFile !== '') argv.push('--cookie-file', args.cookieFile);
486
+ if (Array.isArray(args.headers)) {
487
+ for (const header of args.headers) argv.push('-H', header);
488
+ }
489
+ return [...argv, '--', args.url];
490
+ }
491
+
492
+ /**
493
+ * Execute one `moli fetch` request and materialize its result.
494
+ *
495
+ * Ordinary failures come back as `ok: false` values so the model can react; only
496
+ * a malformed request throws.
497
+ *
498
+ * @param options - resolved executable, validated arguments, and output policy.
499
+ * @returns the canonical tool value.
500
+ */
501
+ export function runFetch(options) {
502
+ // The configured no-verify default applies only when the call stays silent;
503
+ // an explicit false still means "verify fully".
504
+ const args = options.insecureTls === true && options.args.insecureTls === undefined
505
+ ? { ...options.args, insecureTls: true }
506
+ : options.args;
507
+ // `selector` replaces the whole-page output, so combining it with either reader is a
508
+ // call that cannot do what it says: one of the two would be silently ignored. That
509
+ // is the failure mode this plugin keeps having to fix, so it is refused up front and
510
+ // as a structured result, the same way a binary dump with no writeTo is.
511
+ if (typeof args.selector === 'string' && args.selector.trim() !== '') {
512
+ if (args.dump !== undefined) {
513
+ return {
514
+ ok: false,
515
+ url: args.url,
516
+ selector: args.selector,
517
+ error: '`selector` and `dump` cannot be combined: a selector returns one container\'s text and a dump returns the whole page, so one of them could only be ignored',
518
+ hint: 'Use `selector` to read part of the page, or `dump` to read all of it.',
519
+ };
520
+ }
521
+ if (args.eval !== undefined && args.eval !== '') {
522
+ return {
523
+ ok: false,
524
+ url: args.url,
525
+ selector: args.selector,
526
+ error: '`selector` and `eval` cannot be combined: only one expression value can be returned',
527
+ hint: 'Put the extra work in `eval` and drop `selector`, or keep `selector` and read the text it returns.',
528
+ };
529
+ }
530
+ }
531
+ const argv = buildArgs(args);
532
+ const timeoutMs = args.timeoutMs ?? 30000;
533
+ const isBinary = BINARY_DUMPS.has(args.dump);
534
+
535
+ // Reject a byte-returning dump with nowhere to put it before spending a fetch.
536
+ if (isBinary && (args.writeTo === undefined || args.writeTo === '')) {
537
+ return {
538
+ ok: false,
539
+ url: args.url,
540
+ error: `dump "${String(args.dump)}" produces bytes and cannot be returned as text`,
541
+ sandboxTlsBlock: false,
542
+ hint: `Pass writeTo with an absolute .${args.dump === 'pdf' ? 'pdf' : 'png'} path, then read that file.`,
543
+ };
544
+ }
545
+
546
+ const outcome = fetchOnce({
547
+ exe: options.exe,
548
+ args: argv,
549
+ timeoutMs,
550
+ proxy: options.proxy,
551
+ });
552
+
553
+ const bytes = outcome.stdout.length;
554
+ const stderr = outcome.spawnError === undefined ? outcome.stderr : `${outcome.spawnError} | ${outcome.stderr}`;
555
+
556
+ // Empty stdout on a zero exit is not a failure: a page can legitimately have
557
+ // no content in the requested format, which is exactly what a client-rendered
558
+ // page yields under `noJs` with a text dump. moli is right to print nothing
559
+ // for it, and the old code answered with "moli exited with status 0 and no
560
+ // output" plus a hint to re-check the install, sending the caller after a host
561
+ // that was never broken.
562
+ //
563
+ // Both decisions live in this one branch on purpose. Splitting them -- empty
564
+ // stdout treated as success here and stderr checked further down -- lets the
565
+ // case below (silent stdout, a complaint on stderr, exit 0) fall through to
566
+ // the normal success path with the complaint silently dropped.
567
+ if (outcome.status === 0 && bytes === 0) {
568
+ if (stderr !== '') {
569
+ return {
570
+ ok: false,
571
+ url: args.url,
572
+ error: stderr,
573
+ sandboxTlsBlock: isSandboxTlsFailure(stderr),
574
+ unreachable: false,
575
+ possiblyUnreachable: false,
576
+ hint: 'The engine exited cleanly but produced no output and explained why on stderr; the text above is its own message.',
577
+ };
578
+ }
579
+ return {
580
+ ok: true,
581
+ url: args.url,
582
+ kind: 'text',
583
+ dump: args.dump ?? 'html',
584
+ content: '',
585
+ chars: 0,
586
+ bytes: 0,
587
+ empty: true,
588
+ note: 'moli succeeded and produced no output, so the page had no content in this format. '
589
+ + 'A page whose content is built by JavaScript yields nothing when noJs is set; '
590
+ + 'the same URL renders normally without it.',
591
+ };
592
+ }
593
+
594
+ // The engine signals an HTTP error with exit code 22 and, under
595
+ // `--fail-with-body`, keeps whatever the output format produced. That is why the
596
+ // body is still here: the caller is told the fetch failed *and* gets to read what
597
+ // came back, which is what an error page is for.
598
+ //
599
+ // This branch is reached for binary dumps too -- a screenshot of an error page is
600
+ // still a screenshot -- so it must not decode stdout as text.
601
+ if (outcome.status === ENGINE_HTTP_ERROR_STATUS && bytes > 0) {
602
+ // The status is in the stderr reason. A JSON dump also carries it in the body,
603
+ // which is the fallback when the reason wording changes.
604
+ const reported = httpStatusFrom(stderr);
605
+ if (isBinary) {
606
+ const failure = ensureWritable(args.writeTo);
607
+ if (failure !== undefined) {
608
+ return { ok: false, url: args.url, httpError: true, error: failure, hint: 'Pass an absolute path in an existing directory.' };
609
+ }
610
+ writeFileSync(args.writeTo, outcome.stdout);
611
+ return {
612
+ ok: false,
613
+ url: args.url,
614
+ kind: 'binary',
615
+ dump: args.dump,
616
+ path: args.writeTo,
617
+ bytes,
618
+ httpError: true,
619
+ ...(reported === undefined ? {} : { status: reported }),
620
+ error: stderr.trim() === '' ? 'the server answered with an HTTP error status' : stderr.trim(),
621
+ hint: `The image the server returned was written to ${String(args.writeTo)}. Drop \`failOnHttpError\` to treat this as ordinary output.`,
622
+ };
623
+ }
624
+ const text = outcome.stdout.toString('utf8');
625
+ const status = reported
626
+ ?? (args.dump === 'json' && text.trimStart().startsWith('{') ? parseStatus(text) : undefined);
627
+ return {
628
+ ok: false,
629
+ url: args.url,
630
+ httpError: true,
631
+ ...(status === undefined ? {} : { status }),
632
+ error: stderr.trim() === ''
633
+ ? `the server answered with an HTTP error status${status === undefined ? '' : ` (${String(status)})`}`
634
+ : stderr.trim(),
635
+ content: text,
636
+ chars: text.length,
637
+ hint: 'The request reached a server and it refused. The content above is the error page as the engine rendered it, '
638
+ + 'so it is often worth reading. Drop `failOnHttpError` to treat this as ordinary content instead.',
639
+ };
640
+ }
641
+
642
+ if (outcome.status !== 0) {
643
+ const sandboxTls = isSandboxTlsFailure(stderr);
644
+ // A blocked host fails at connect time ("Failed to connect" / RST) or, when
645
+ // the socket never opens, as a readiness timeout with nothing to show. A
646
+ // readiness timeout can also mean a genuinely slow page, so it is reported
647
+ // as *possibly* unreachable and worded as a suggestion rather than a verdict.
648
+ const { unreachable, possiblyUnreachable, conditionTimedOut } = isUnreachableFailure(stderr);
649
+ // The engine reports a thrown expression as
650
+ // `Reason: JavaScript evaluation failed: TypeError: ... at <anonymous>:1:6`
651
+ // which is a bug in the call, not an install or network problem. Falling
652
+ // through to the generic hint below used to tell the caller to re-check the
653
+ // installation with moli_probe, which cannot possibly help.
654
+ const evalFailure = args.eval !== undefined && /JavaScript evaluation failed/u.test(stderr);
655
+ // A binary dump that failed produced no file at all. Saying only "exited with
656
+ // status 1" leaves the caller to guess whether an image exists; the useful fact
657
+ // is that it does not, and that a text dump would have captured this page.
658
+ const binaryFailure = isBinary && httpStatusFrom(stderr) !== undefined;
659
+ // Name the wait that never resolved. "Retry or set a proxy" is actively
660
+ // misleading here: the page arrived, so the network is fine, and the caller
661
+ // would spend their time on the one part of the setup that is working.
662
+ const conditionHint = args.waitSelector !== undefined
663
+ ? `The selector ${JSON.stringify(args.waitSelector)} never matched. The page loaded, so this is not a network problem: check the spelling, and confirm the element is there with \`selector\` (it reports the match count, where a wait only times out) or \`dump\`.`
664
+ : args.waitScript !== undefined
665
+ ? 'The wait expression never became truthy. The page loaded, so this is not a network problem: check the expression against the page with `eval`, and remember it is polled rather than evaluated once.'
666
+ : (args.waitResponseUrl !== undefined || args.waitResponseJson !== undefined)
667
+ ? 'No response matching that condition arrived. The page loaded, so this is not a network problem: the request may never be made, or its payload may differ from what you matched on. Use `dump` with a short timeout to see what the page does, or an `eval` that inspects the fetch.'
668
+ : 'The wait condition never became true. The page loaded, so this is not a network problem: check the condition.';
669
+ const hint = evalFailure
670
+ ? 'The eval expression threw. Check that the page has reached the state you expect (`wait` or `waitSelector`), that the selector matches an element, and that the expression is valid JavaScript. The engine error names the type and position.'
671
+ : binaryFailure
672
+ ? 'The engine could not render this page, so no file was written. An HTTP error still produces a body for a text dump (markdown, html or json), so ask for one of those if you need to see what the server returned.'
673
+ : sandboxTls
674
+ ? 'The DSH file sandbox blocks Schannel client credentials, so moli cannot do TLS at low integrity. Retry the same call with sandbox_permissions "danger-full-access" (with a justification), use an http:// URL, or pass proxy to reach a local forward proxy.'
675
+ : conditionTimedOut
676
+ ? conditionHint
677
+ : possiblyUnreachable
678
+ ? 'The host did not answer in time. Reachability to some hosts varies on this network, so retrying may succeed; if a local forward proxy is available, setting the plugin config field `proxy` is the other option. A certificate problem would report a schannel error instead of a timeout.'
679
+ : 'Run moli_probe to confirm the install, then retry; use waitSelector or eval for a page that renders late.';
680
+ const failureStatus = httpStatusFrom(stderr);
681
+ return {
682
+ ok: false,
683
+ url: args.url,
684
+ ...(failureStatus === undefined ? {} : { status: failureStatus, httpError: true }),
685
+ error: stderr === '' ? `moli exited with status ${String(outcome.status)} and no output` : stderr,
686
+ sandboxTlsBlock: sandboxTls,
687
+ unreachable,
688
+ possiblyUnreachable,
689
+ ...(conditionTimedOut ? { conditionTimedOut: true } : {}),
690
+ ...(evalFailure ? { evalFailed: true } : {}),
691
+ hint,
692
+ };
693
+ }
694
+
695
+ if (isBinary) {
696
+ const failure = ensureWritable(args.writeTo);
697
+ if (failure !== undefined) {
698
+ return { ok: false, url: args.url, error: failure, sandboxTlsBlock: false, hint: 'Pass an absolute path in an existing directory.' };
699
+ }
700
+ // A binary dump produces nothing for an HTTP error: the engine exits 1 before
701
+ // rendering anything, unlike the text dumps which exit 22 with the body kept.
702
+ // Nothing is written, so say that rather than leaving an empty file behind.
703
+ if (outcome.status !== 0) {
704
+ const status = httpStatusFrom(stderr);
705
+ return {
706
+ ok: false,
707
+ url: args.url,
708
+ ...(status === undefined ? {} : { status }),
709
+ httpError: outcome.status === ENGINE_HTTP_ERROR_STATUS || status !== undefined,
710
+ error: stderr.trim() === '' ? `moli exited with status ${String(outcome.status)} before producing ${String(args.dump)} output` : stderr.trim(),
711
+ hint: 'The engine could not render this page, so no file was written. A text dump (markdown, html or json) still captures an HTTP error body; binary output does not.',
712
+ };
713
+ }
714
+ writeFileSync(args.writeTo, outcome.stdout);
715
+ return {
716
+ ok: true,
717
+ url: args.url,
718
+ kind: 'binary',
719
+ dump: args.dump,
720
+ path: args.writeTo,
721
+ bytes,
722
+ note: 'Binary output was written verbatim; read the file instead of asking moli to print it.',
723
+ };
724
+ }
725
+
726
+ const text = outcome.stdout.toString('utf8');
727
+ // A selector result comes back as our own sentinel, because an empty selection and
728
+ // a page with no text are both an empty string from the engine -- verified: an
729
+ // expression returning `""` exits 0 with an empty line. Reporting "matched
730
+ // nothing" is the entire value of asking by selector, so it must not be silent.
731
+ if (typeof args.selector === 'string' && args.selector.trim() !== '') {
732
+ const payload = parseSelectorResult(text);
733
+ if (payload === undefined) {
734
+ return {
735
+ ok: false,
736
+ url: args.url,
737
+ selector: args.selector,
738
+ error: `the selector result could not be read: the engine returned ${JSON.stringify(text.slice(0, 120))}`,
739
+ hint: 'The page may not have finished rendering. Try waitSelector, or wait for the content with waitResponseUrl.',
740
+ };
741
+ }
742
+ if (payload.matched === 0) {
743
+ return {
744
+ ok: false,
745
+ url: args.url,
746
+ selector: args.selector,
747
+ matched: 0,
748
+ error: `no element matches ${JSON.stringify(args.selector)}`,
749
+ hint: 'The selector found nothing on this page. Check the spelling, wait for the content to arrive (`waitSelector`, `waitResponseUrl`), or use `dump` to see what the page actually contains.',
750
+ };
751
+ }
752
+ if (payload.withText === 0) {
753
+ return {
754
+ ok: false,
755
+ url: args.url,
756
+ selector: args.selector,
757
+ matched: payload.matched,
758
+ error: `${String(payload.matched)} element(s) match ${JSON.stringify(args.selector)} but none of them has any text`,
759
+ hint: 'The elements are probably images, icons or empty containers. Use `eval` if you need their attributes rather than their text.',
760
+ };
761
+ }
762
+ return {
763
+ ok: true,
764
+ url: args.url,
765
+ kind: 'text',
766
+ selector: args.selector,
767
+ content: payload.joined,
768
+ chars: payload.joined.length,
769
+ matched: payload.matched,
770
+ ...(payload.matched > payload.withText
771
+ ? { note: `${String(payload.matched - payload.withText)} of the ${String(payload.matched)} matched elements had no text and were left out.` }
772
+ : {}),
773
+ };
774
+ }
775
+ // `eval` together with `dump` is the engine's documented behaviour -- it discards
776
+ // the expression's value and dumps the page state the expression produced -- but
777
+ // it reads as a successful answer to a question that was never answered. The
778
+ // caller asked for `{probe:1}` and got 900 characters of Markdown. The discard is
779
+ // kept, because mutating a page before capturing it is a real use, so the result
780
+ // has to say what happened instead of looking clean.
781
+ const evalDiscarded = args.eval !== undefined && args.eval !== '' && args.dump !== undefined;
782
+ const evalNote = evalDiscarded
783
+ ? 'The `eval` expression produced no value here: `dump` was given too, and the engine discards the expression result in that combination. The output above is the page, not the expression. Run again with `eval` alone for the value, or keep both deliberately when the expression only changes the page before it is captured.'
784
+ : undefined;
785
+ // A JSON dump is the only format that reports the HTTP status, so an error
786
+ // page is otherwise indistinguishable from content. Surface it rather than
787
+ // letting the model read a 404 body as if the fetch succeeded.
788
+ const httpStatus = args.dump === 'json' && text.trimStart().startsWith('{')
789
+ ? parseStatus(text)
790
+ : undefined;
791
+ if (typeof httpStatus === 'number' && httpStatus >= 400) {
792
+ return {
793
+ ok: false,
794
+ url: args.url,
795
+ status: httpStatus,
796
+ error: `the server answered HTTP ${String(httpStatus)}`,
797
+ sandboxTlsBlock: false,
798
+ hint: 'The request reached the server; the URL or credentials are the problem, not the network.',
799
+ };
800
+ }
801
+ if (args.writeTo !== undefined && args.writeTo !== '') {
802
+ const failure = ensureWritable(args.writeTo);
803
+ if (failure !== undefined) {
804
+ return { ok: false, url: args.url, error: failure, sandboxTlsBlock: false, hint: 'Pass an absolute path in an existing directory.' };
805
+ }
806
+ writeFileSync(args.writeTo, outcome.stdout);
807
+ return {
808
+ ok: true,
809
+ url: args.url,
810
+ kind: 'text',
811
+ dump: args.dump ?? 'html',
812
+ path: args.writeTo,
813
+ chars: text.length,
814
+ bytes,
815
+ note: evalNote === undefined
816
+ ? 'Full output saved to file; read it for the complete text.'
817
+ : `Full output saved to file; read it for the complete text. ${evalNote}`,
818
+ ...(evalDiscarded ? { evalDiscarded: true } : {}),
819
+ };
820
+ }
821
+
822
+ const limit = args.maxChars ?? options.maxChars;
823
+ const truncated = typeof limit === 'number' && limit > 0 && text.length > limit;
824
+ // Keep the head and the tail rather than only the head. For a rendered page the
825
+ // head is chrome -- a nav bar, a consent banner, dozens of image placeholders --
826
+ // so a head-only slice can return 200,000 characters of navigation and none of
827
+ // the content the caller asked for. Splitting the budget keeps whatever the page
828
+ // ends with, and the note says exactly what went missing so the caller can decide
829
+ // whether to re-fetch with writeTo.
830
+ let content = text;
831
+ let note;
832
+ let omitted;
833
+ if (truncated) {
834
+ // Reserve room for the marker, but never let it swallow a small budget.
835
+ const reserve = Math.min(240, Math.floor(limit / 8));
836
+ const budget = Math.max(2, limit - reserve);
837
+ const headLen = Math.ceil(budget * 0.6);
838
+ const tailLen = budget - headLen;
839
+ omitted = text.length - budget;
840
+ // The marker inside the body is only a position signal: where the gap is and how
841
+ // big it is. Everything actionable -- the head/tail split, the total, the writeTo
842
+ // escape -- lives in the note, which is rendered once at the top. Both used to
843
+ // say the same thing, and on a 2,000-character budget the two copies cost 12.6%
844
+ // of everything the model received.
845
+ const mark = `\n\n… [dsh-moli] ${String(omitted)} characters omitted …\n\n`;
846
+ content = text.slice(0, headLen) + mark + text.slice(text.length - tailLen);
847
+ note = `Truncated to fit maxChars: the first ${String(headLen)} and the last ${String(tailLen)} of ${String(text.length)} characters are shown, with ${String(omitted)} omitted in the middle. Pass writeTo to keep all ${String(text.length)}.`;
848
+ }
849
+ // `eval` together with `dump` is the engine's documented behaviour -- it discards
850
+ // the expression's value and dumps the page state the expression produced -- but
851
+ // it reads as a successful answer to a question that was never answered. The
852
+ // caller asked for `{probe:1}` and got 900 characters of Markdown. The value is
853
+ // still discarded (that combination is genuinely useful for mutating a page before
854
+ // capturing it), so the result has to say so rather than look clean.
855
+ return {
856
+ ok: true,
857
+ url: args.url,
858
+ kind: 'text',
859
+ dump: args.dump ?? 'html',
860
+ content,
861
+ chars: text.length,
862
+ bytes,
863
+ truncated,
864
+ ...(truncated ? { omitted } : {}),
865
+ ...(evalDiscarded ? { evalDiscarded: true } : {}),
866
+ ...(note === undefined && evalNote === undefined
867
+ ? {}
868
+ : { note: [note, evalNote].filter(part => part !== undefined).join(' ') }),
869
+ };
870
+ }
871
+
872
+ /**
873
+ * Read the payload {@link selectorScript} prefixes onto its result.
874
+ *
875
+ * The engine prints the expression value verbatim, so the script adds a sentinel to
876
+ * tell a selector answer apart from page text. Anything without the sentinel is not
877
+ * a selector answer and comes back as undefined, which the caller reports as a
878
+ * failure rather than dressing it up as content.
879
+ *
880
+ * @param text - the engine's stdout.
881
+ * @returns `{ matched, withText, joined }`, or undefined.
882
+ */
883
+ function parseSelectorResult(text) {
884
+ const marker = '[dsh-moli:selector]';
885
+ const at = String(text).indexOf(marker);
886
+ if (at < 0) return undefined;
887
+ try {
888
+ const raw = JSON.parse(String(text).slice(at + marker.length).trim());
889
+ if (raw === null || typeof raw !== 'object') return undefined;
890
+ if (typeof raw.matched !== 'number' || typeof raw.joined !== 'string') return undefined;
891
+ return {
892
+ matched: raw.matched,
893
+ withText: typeof raw.withText === 'number' ? raw.withText : 0,
894
+ joined: raw.joined,
895
+ };
896
+ } catch {
897
+ return undefined;
898
+ }
899
+ }
900
+
901
+ /**
902
+ * Read the HTTP status out of the engine's stderr reason.
903
+ *
904
+ * The engine reports it there, in the form
905
+ * `Reason: final main document returned HTTP status 404 at ...`
906
+ * for `--fail` and `--fail-with-body`, whatever the dump format. That makes stderr
907
+ * the reliable source: a JSON dump also carries the status in its body, but a
908
+ * markdown or HTML dump does not, and this branch has to name the status for those
909
+ * too. Matching narrowly keeps an unrelated number in the text from being read as a
910
+ * status.
911
+ *
912
+ * @param stderr - the engine's stderr text.
913
+ * @returns the numeric status, or undefined when it is not reported.
914
+ */
915
+ function httpStatusFrom(stderr) {
916
+ const match = /HTTP status (\d{3})\b/u.exec(String(stderr));
917
+ return match === null ? undefined : Number(match[1]);
918
+ }
919
+
920
+ /**
921
+ * Read the HTTP status out of a JSON dump without trusting its shape.
922
+ *
923
+ * @param text - the dump's JSON text.
924
+ * @returns the numeric status, or undefined when it is absent or not a number.
925
+ */
926
+ function parseStatus(text) {
927
+ try {
928
+ const parsed = JSON.parse(text);
929
+ return typeof parsed.status === 'number' ? parsed.status : undefined;
930
+ } catch {
931
+ return undefined;
932
+ }
933
+ }
934
+
935
+ /**
936
+ * Check that an output path can be created before the engine runs.
937
+ *
938
+ * @param path - requested destination path.
939
+ * @returns an error message, or undefined when the path looks usable.
940
+ */
941
+ function ensureWritable(path) {
942
+ const parent = dirname(path);
943
+ if (!existsSync(parent)) return `destination directory does not exist: ${parent}`;
944
+ if (existsSync(path) && !statIsFile(path)) return `destination is not a regular file: ${path}`;
945
+ return undefined;
946
+ }
947
+
948
+ /**
949
+ * Whether a path exists as a regular file.
950
+ *
951
+ * @param path - candidate path.
952
+ * @returns whether it is a file.
953
+ */
954
+ function statIsFile(path) {
955
+ try {
956
+ return statSync(path).isFile();
957
+ } catch {
958
+ return false;
959
+ }
960
+ }
961
+
962
+ /**
963
+ * Report whether the engine exists and can reach HTTPS from this process.
964
+ *
965
+ * @param exe - absolute path to `moli.exe`.
966
+ * @param probeUrl - an HTTPS URL to fetch in text mode.
967
+ * @returns the diagnostic value.
968
+ */
969
+ export function probe(exe, probeUrl, insecureTls = false) {
970
+ const version = moliVersion(exe);
971
+ const probeArgs = ['fetch', probeUrl, '-d', 'markdown'];
972
+ if (insecureTls) probeArgs.push('--insecure-disable-tls-host-verification');
973
+ const outcome = fetchOnce({ exe, args: probeArgs, timeoutMs: 20000 });
974
+ const stderr = outcome.spawnError === undefined ? outcome.stderr : `${outcome.spawnError} | ${outcome.stderr}`;
975
+ // A zero exit means moli reached the host and fetched it. Requiring non-empty
976
+ // stdout as well would report httpsOk:false for a page that simply has no
977
+ // text — a probe URL is not guaranteed to carry content, and the field is
978
+ // documented as "can reach HTTPS", which is what the exit status proves.
979
+ const ok = outcome.status === 0;
980
+ const revocation = /CRYPT_E_REVOCATION_OFFLINE|revocation/iu.test(stderr);
981
+ return {
982
+ exe,
983
+ version: version ?? 'unknown',
984
+ // `httpsOk` describes the process that ran this call, which for the plugin is
985
+ // the DSH host. It says nothing about whether a separate restricted shell can
986
+ // reach the network -- under the file sandbox that shell fails on TLS while
987
+ // this path succeeds, so the scope is stated rather than implied.
988
+ httpsOkScope: 'the process that ran this probe (the DSH host process when called through moli_probe), not any other shell on this machine',
989
+ httpsOk: ok,
990
+ probeUrl,
991
+ detail: ok
992
+ ? (outcome.stdout.length > 0
993
+ ? 'HTTPS fetch succeeded from the DSH host process.'
994
+ : 'HTTPS fetch succeeded from the DSH host process (the probe URL returned no text).')
995
+ : revocation && !insecureTls
996
+ ? `${stderr} | This is a certificate-revocation check failing (offline CRL/OCSP responder); retrying with the no-verify flag normally clears it.`
997
+ : stderr,
998
+ sandboxTlsBlock: isSandboxTlsFailure(stderr),
999
+ revocationBlock: revocation,
1000
+ };
1001
+ }