@mjasnikovs/pi-task 0.38.15 → 0.38.17

package/dist/workers/docs-core.js

@@ -176,7 +176,8 @@ export function ensureDocsModulesDir(dir) {
         fs.writeFileSync(pkgPath, '{"name":"pi-worker-docs-modules","private":true}\n', 'utf8');
     }
 }
-export async function runAutoInstall(spawn, packageName, signal, versionRange) {
+export async function runAutoInstall(spawn, packageName, opts = {}) {
+    const { signal, versionRange } = opts;
     const installDir = getDocsModulesDir();
     ensureDocsModulesDir(installDir);
     // `shell: false` in runChild, so a `^`/`~`/space in the range stays a single
@@ -203,31 +204,97 @@ export async function runAutoInstall(spawn, packageName, signal, versionRange) {
     }, installDir, signal, { mode: 'text', discardStdout: true });
     return { success: result.exitCode === 0 && !result.aborted, installDir, stderr: result.stderr };
 }
-/** Resolve `name` from cwd; on `not_installed`, auto-install it and resolve from
- *  the install dir. Returns null on any failure (caller keeps its fallback). */
-async function tryResolveOrInstall(name, cwd, spawn, resolvePackage, signal) {
+/**
+ * Get a package onto disk and resolved: resolve from `cwd`, and on
+ * `not_installed` install it — at the range the PROJECT declares when it declares
+ * one — then resolve again from the install dir.
+ *
+ * One statement of the ladder, for both callers. It was written twice: inline in
+ * `docsRaw` for the requested package, and in `tryResolveOrInstall` for each hop
+ * of the type-redirect chain — and the copies had drifted on all three things
+ * that matter.
+ *
+ *  - The abort signal. The hop copy passed it; the primary copy passed a bare
+ *    `undefined` placeholder to reach the fourth positional, while
+ *    `DocsRawInput.signal` was honoured on either side of that call. So a user
+ *    cancel during the MAIN `npm install` of a model-chosen package was not
+ *    delivered. `runAutoInstall` takes an options object now, so a hole like that
+ *    cannot be typed.
+ *  - The version pin. `findDeclaredRange` had exactly one call site — the primary
+ *    copy. The hop copy installed `latest` unconditionally, on the hop most likely
+ *    to be the declared one: `declarationChain` exists precisely because "a
+ *    project that uses Bun declares `@types/bun`, not `bun`".
+ *  - The provenance. `autoInstalled`/`autoInstallPin` were locals of `docsRaw`, so
+ *    a package acquired only through a hop reported neither and got no version
+ *    banner.
+ *
+ * CONTEXT.md records the redirect WALK as unified (`resolveTypeSource`) and its
+ * `resolveHop` seam as "the one thing its two call sites disagree about". They
+ * should disagree only about WHETHER to install, never about HOW.
+ */
+export async function acquirePackage(input) {
+    const { name, cwd, spawn, resolvePackage, signal } = input;
     try {
-        return resolvePackage(name, cwd);
+        return { ok: true, pkg: resolvePackage(name, cwd), autoInstalled: false };
     }
-    catch (err) {
-        if (!(err instanceof ResolveError) || err.kind !== 'not_installed')
-            return null;
-        const install = await runAutoInstall(spawn, extractParentPackage(name), signal);
-        if (!install.success)
-            return null;
+    catch (firstErr) {
+        if (!(firstErr instanceof ResolveError) || firstErr.kind !== 'not_installed') {
+            return { ok: false, stage: 'resolve', err: firstErr };
+        }
+        // Auto-install — but FIRST honour the version the project intends. If the
+        // dep is declared in the project's package.json, install that range so a
+        // scaffolding answer is grounded in the project's major, not whatever npm
+        // currently tags `latest`.
+        const asked = extractParentPackage(name);
+        const declaredRange = findDeclaredRange(asked, cwd);
+        const pin = declaredRange ?
+            { source: 'declared-range', range: declaredRange, asked }
+            : { source: 'npm-latest', asked };
+        const install = await runAutoInstall(spawn, asked, {
+            signal,
+            versionRange: declaredRange ?? undefined
+        });
+        if (!install.success) {
+            return { ok: false, stage: 'install', stderr: install.stderr, pin, asked };
+        }
         try {
-            return resolvePackage(name, install.installDir);
+            return {
+                ok: true,
+                pkg: resolvePackage(name, install.installDir),
+                autoInstalled: true,
+                pin
+            };
         }
-        catch {
-            return null;
+        catch (retryErr) {
+            return { ok: false, stage: 'reresolve', err: retryErr, pin };
         }
     }
 }
+/** Resolve `name` from cwd; on `not_installed`, auto-install it and resolve from
+ *  the install dir. Returns null on any failure (caller keeps its fallback). */
+async function tryResolveOrInstall(name, cwd, spawn, resolvePackage, signal, onAcquired) {
+    const got = await acquirePackage({ name, cwd, spawn, resolvePackage, signal });
+    if (!got.ok)
+        return null;
+    if (got.autoInstalled)
+        onAcquired?.(got.pin);
+    return got.pkg;
+}
 /** The docs pipeline's adapter over the shared redirect walk (docs-resolve.ts):
  *  hops resolve through the auto-installing lookup, so a declaration package that is
  *  declared but not yet on disk is fetched rather than abandoned. */
-function resolveTypeSourceForDocs(pkg, requested, cwd, spawn, resolvePackage, signal) {
-    return resolveTypeSource(pkg, extractParentPackage(requested), next => tryResolveOrInstall(next, cwd, spawn, resolvePackage, signal));
+async function resolveTypeSourceForDocs(pkg, requested, cwd, spawn, resolvePackage, signal) {
+    // A package acquired ONLY through a hop used to report neither `autoInstalled`
+    // nor a pin, so `pi-worker-docs` emitted no version banner for it — while the
+    // banner's own text ("only its types are, as `@types/bun` `^1.2`") claims a
+    // range as provenance. Report the last hop that actually installed.
+    let installed = false;
+    let pin;
+    const out = await resolveTypeSource(pkg, extractParentPackage(requested), next => tryResolveOrInstall(next, cwd, spawn, resolvePackage, signal, hopPin => {
+        installed = true;
+        pin = hopPin;
+    }));
+    return pin ? { pkg: out, installed, pin } : { pkg: out, installed };
 }
 export async function docsRaw(input) {
     const resolvePackage = input.resolvePackage ?? defaultResolvePackage;
@@ -247,83 +314,76 @@ export async function docsRaw(input) {
     const npmVersionPromise = npmVersionLookup(extractParentPackage(requested), {
         signal: input.signal
     }).catch(() => null);
-    // Step 1: resolve package
-    let pkg;
-    let autoInstalled = false;
-    let autoInstallPin;
-    try {
-        pkg = resolvePackage(requested, input.cwd);
-    }
-    catch (firstErr) {
-        if (firstErr instanceof ResolveError && firstErr.kind === 'not_installed') {
-            // auto-install — but FIRST honour the version the project intends.
-            // If the dep is declared in the project's package.json, install that
-            // range so a scaffolding answer is grounded in the project's major,
-            // not whatever npm currently tags `latest`.
-            const parentPkg = extractParentPackage(requested);
-            const declaredRange = findDeclaredRange(parentPkg, input.cwd);
-            autoInstallPin =
-                declaredRange ?
-                    { source: 'declared-range', range: declaredRange, asked: parentPkg }
-                    : { source: 'npm-latest', asked: parentPkg };
-            const installResult = await runAutoInstall(spawn, parentPkg, undefined, declaredRange ?? undefined);
-            if (!installResult.success) {
-                return {
-                    kind: 'error',
-                    message: `Package "${parentPkg}" is not installed and auto-install failed.\n${installResult.stderr}`,
-                    resolveError: 'not_installed',
-                    installError: installResult.stderr,
-                    autoInstallPin,
-                    npmVersion: await npmVersionPromise
-                };
-            }
-            autoInstalled = true;
-            try {
-                pkg = resolvePackage(requested, installResult.installDir);
-            }
-            catch (retryErr) {
-                if (retryErr instanceof ResolveError) {
-                    return {
-                        kind: 'error',
-                        message: retryErr.message,
-                        resolveError: retryErr.kind,
-                        autoInstalled,
-                        autoInstallPin,
-                        npmVersion: await npmVersionPromise
-                    };
-                }
+    // Step 1: acquire the package — resolve, or install-at-the-declared-range and
+    // resolve again. The ladder is `acquirePackage`; this maps its stages onto the
+    // rich error results the docs tool reports. `input.signal` now reaches the
+    // install, which it never did while the range was a fourth positional.
+    const got = await acquirePackage({
+        name: requested,
+        cwd: input.cwd,
+        spawn,
+        resolvePackage,
+        signal: input.signal
+    });
+    if (!got.ok) {
+        if (got.stage === 'install') {
+            return {
+                kind: 'error',
+                message: `Package "${got.asked}" is not installed and auto-install failed.\n${got.stderr}`,
+                resolveError: 'not_installed',
+                installError: got.stderr,
+                autoInstallPin: got.pin,
+                npmVersion: await npmVersionPromise
+            };
+        }
+        if (got.stage === 'reresolve') {
+            if (got.err instanceof ResolveError) {
                 return {
                     kind: 'error',
-                    message: `Could not resolve "${input.pkg}" after install: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`,
-                    autoInstalled,
-                    autoInstallPin,
+                    message: got.err.message,
+                    resolveError: got.err.kind,
+                    autoInstalled: true,
+                    autoInstallPin: got.pin,
                     npmVersion: await npmVersionPromise
                 };
             }
-        }
-        else if (firstErr instanceof ResolveError) {
             return {
                 kind: 'error',
-                message: firstErr.message,
-                resolveError: firstErr.kind,
+                message: `Could not resolve "${input.pkg}" after install: ${got.err instanceof Error ? got.err.message : String(got.err)}`,
+                autoInstalled: true,
+                autoInstallPin: got.pin,
                 npmVersion: await npmVersionPromise
             };
         }
-        else {
+        if (got.err instanceof ResolveError) {
             return {
                 kind: 'error',
-                message: `Could not resolve "${input.pkg}": ${firstErr instanceof Error ? firstErr.message : String(firstErr)}`,
+                message: got.err.message,
+                resolveError: got.err.kind,
                 npmVersion: await npmVersionPromise
             };
         }
+        return {
+            kind: 'error',
+            message: `Could not resolve "${input.pkg}": ${got.err instanceof Error ? got.err.message : String(got.err)}`,
+            npmVersion: await npmVersionPromise
+        };
     }
+    let pkg = got.pkg;
+    let autoInstalled = got.autoInstalled;
+    let autoInstallPin = got.pin;
     // Step 1b: if the resolved package ships no usable type declarations (e.g.
     // the `bun` runtime launcher, which is just a binary + install README), or is
     // a pure `@types/<name>` redirect stub, follow the conventional
     // @types/<name> + triple-slash `<reference types>` chain to the package that
     // actually holds the declarations (e.g. bun -> @types/bun -> bun-types).
     // Best-effort: any failure leaves the original resolution untouched.
-    pkg = await resolveTypeSourceForDocs(pkg, requested, input.cwd, spawn, resolvePackage, input.signal);
+    const viaTypes = await resolveTypeSourceForDocs(pkg, requested, input.cwd, spawn, resolvePackage, input.signal);
+    pkg = viaTypes.pkg;
+    if (viaTypes.installed) {
+        autoInstalled = true;
+        autoInstallPin ??= viaTypes.pin;
+    }
     // Step 2: open cache
     let cache = null;
     let cacheError;

package/dist/workers/exa-search.d.ts

@@ -7,9 +7,9 @@
  * and the result payload is one text blob of `Title:`/`URL:`/`Text:` blocks
  * separated by `---`, which we parse back into structured results.
  */
+import { type FetchLike } from './http-request.js';
 import type { SearchResult } from './search-types.js';
-/** Injectable fetch — the narrow signature keeps test fakes free of Bun's extras. */
-export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export type { FetchLike };
 export interface ExaSearchOpts {
     count?: number;
     timeoutMs?: number;

package/dist/workers/exa-search.js

@@ -7,6 +7,7 @@
  * and the result payload is one text blob of `Title:`/`URL:`/`Text:` blocks
  * separated by `---`, which we parse back into structured results.
  */
+import { httpRequest, HttpRequestError } from './http-request.js';
 const EXA_MCP_ENDPOINT = 'https://mcp.exa.ai/mcp';
 const DEFAULT_COUNT = 10;
 const MAX_COUNT = 20;
@@ -24,72 +25,61 @@ export class ExaSearchError extends Error {
 }
 export async function exaSearch(query, opts = {}) {
     const count = Math.max(1, Math.min(MAX_COUNT, opts.count ?? DEFAULT_COUNT));
-    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const fetchImpl = opts.fetchImpl ?? fetch;
-    const internalController = new AbortController();
-    let userAborted = false;
-    const timeoutHandle = setTimeout(() => internalController.abort(), timeoutMs);
-    const onUserAbort = () => {
-        userAborted = true;
-        internalController.abort();
-    };
-    if (opts.signal) {
-        if (opts.signal.aborted)
-            onUserAbort();
-        else
-            opts.signal.addEventListener('abort', onUserAbort, { once: true });
-    }
+    return await request({
+        timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        ...(opts.signal === undefined ? {} : { signal: opts.signal }),
+        ...(opts.fetchImpl === undefined ? {} : { fetchImpl: opts.fetchImpl })
+    }, count, query);
+}
+/** The Exa-specific half: its argv, its status policy, its error type. */
+async function request(bounds, count, query) {
     try {
-        let response;
-        try {
-            response = await fetchImpl(EXA_MCP_ENDPOINT, {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    accept: 'application/json, text/event-stream'
-                },
-                body: JSON.stringify({
-                    jsonrpc: '2.0',
-                    id: 1,
-                    method: 'tools/call',
-                    params: {
-                        name: 'web_search_exa',
-                        arguments: {
-                            query,
-                            numResults: count,
-                            type: 'auto',
-                            livecrawl: 'fallback',
-                            contextMaxCharacters: 3000
-                        }
+        return await httpRequest(EXA_MCP_ENDPOINT, {
+            ...bounds,
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json, text/event-stream'
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'tools/call',
+                params: {
+                    name: 'web_search_exa',
+                    arguments: {
+                        query,
+                        numResults: count,
+                        type: 'auto',
+                        livecrawl: 'fallback',
+                        contextMaxCharacters: 3000
                     }
-                }),
-                signal: internalController.signal
-            });
-        }
-        catch (err) {
-            if (userAborted)
-                throw new ExaSearchError('Search aborted.', 'aborted');
-            throw new ExaSearchError(`Exa search request failed: ${describeError(err)}`, 'network');
-        }
-        if (!response.ok) {
-            throw new ExaSearchError(`Exa search HTTP ${response.status} ${response.statusText}`, 'http', response.status);
-        }
-        const rpc = parseRpcBody(await response.text());
-        if (rpc.error) {
-            throw new ExaSearchError(`Exa MCP error${rpc.error.code !== undefined ? ` ${rpc.error.code}` : ''}: ${rpc.error.message ?? 'unknown error'}`, 'protocol');
-        }
-        const text = rpc.result?.content?.find(c => c.type === 'text' && typeof c.text === 'string' && c.text.trim().length > 0)?.text;
-        if (rpc.result?.isError) {
-            throw new ExaSearchError(text?.trim() || 'Exa MCP returned an error result.', 'protocol');
-        }
-        if (!text)
-            throw new ExaSearchError('Exa MCP returned no text content.', 'protocol');
-        return parseResultBlocks(text).slice(0, count);
+                }
+            })
+        }, async (response) => {
+            if (!response.ok) {
+                throw new ExaSearchError(`Exa search HTTP ${response.status} ${response.statusText}`, 'http', response.status);
+            }
+            const rpc = parseRpcBody(await response.text());
+            if (rpc.error) {
+                throw new ExaSearchError(`Exa MCP error${rpc.error.code !== undefined ? ` ${rpc.error.code}` : ''}: ${rpc.error.message ?? 'unknown error'}`, 'protocol');
+            }
+            const text = rpc.result?.content?.find(c => c.type === 'text' && typeof c.text === 'string' && c.text.trim().length > 0)?.text;
+            if (rpc.result?.isError) {
+                throw new ExaSearchError(text?.trim() || 'Exa MCP returned an error result.', 'protocol');
+            }
+            if (!text)
+                throw new ExaSearchError('Exa MCP returned no text content.', 'protocol');
+            return parseResultBlocks(text).slice(0, count);
+        });
     }
-    finally {
-        clearTimeout(timeoutHandle);
-        if (opts.signal)
-            opts.signal.removeEventListener('abort', onUserAbort);
+    catch (err) {
+        if (err instanceof HttpRequestError) {
+            throw err.kind === 'aborted' ?
+                new ExaSearchError('Search aborted.', 'aborted')
+                : new ExaSearchError(`Exa search request failed: ${err.detail}`, 'network');
+        }
+        throw err;
     }
 }
 /**
@@ -157,8 +147,3 @@ function parseResultBlocks(text) {
     }
     return results;
 }
-function describeError(err) {
-    if (err instanceof Error)
-        return err.message;
-    return String(err);
-}

package/dist/workers/html-clean.js

@@ -2,6 +2,7 @@ import { parseHTML } from 'linkedom';
 import { Readability } from '@mozilla/readability';
 import TurndownService from 'turndown';
 import { readPkgVersion } from '../shared/pkg-version.js';
+import { httpRequest, HttpRequestError, describeError } from './http-request.js';
 const turndown = new TurndownService({
     codeBlockStyle: 'fenced',
     headingStyle: 'atx',
@@ -86,100 +87,83 @@ export class FetchAndCleanError extends Error {
     }
 }
 export async function fetchAndClean(url, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
-    const internalController = new AbortController();
     let sizeExceeded = false;
-    let userAborted = false;
-    const timeoutHandle = setTimeout(() => internalController.abort(), timeoutMs);
-    const onUserAbort = () => {
-        userAborted = true;
-        internalController.abort();
-    };
-    if (opts.signal) {
-        if (opts.signal.aborted)
-            onUserAbort();
-        else
-            opts.signal.addEventListener('abort', onUserAbort, { once: true });
-    }
     try {
-        let response;
-        try {
-            response = await fetch(url, {
-                headers: { 'user-agent': USER_AGENT },
-                redirect: 'follow',
-                signal: internalController.signal
-            });
-        }
-        catch (err) {
-            if (userAborted) {
-                throw new FetchAndCleanError('Fetch aborted.', 'aborted', err);
+        return await httpRequest(url, {
+            timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            ...(opts.signal === undefined ? {} : { signal: opts.signal }),
+            headers: { 'user-agent': USER_AGENT },
+            redirect: 'follow'
+        }, async (response, ctl) => {
+            if (!response.ok) {
+                throw new FetchAndCleanError(`Fetch failed: HTTP ${response.status} ${response.statusText} for ${url}`, 'http-error');
             }
-            throw new FetchAndCleanError(`Could not fetch ${url}: ${describeError(err)}`, 'network', err);
-        }
-        if (!response.ok) {
-            throw new FetchAndCleanError(`Fetch failed: HTTP ${response.status} ${response.statusText} for ${url}`, 'http-error');
-        }
-        const contentType = response.headers.get('content-type') ?? '';
-        const kind = classifyContentType(contentType);
-        if (kind === 'reject') {
-            throw new FetchAndCleanError(`${url} is ${contentType || 'unknown content type'}, not a text or HTML page that pi-worker-fetch can read.`, 'not-html');
-        }
-        const reader = response.body?.getReader();
-        if (!reader) {
-            throw new FetchAndCleanError(`Could not fetch ${url}: empty response body`, 'network');
-        }
-        const decoder = decoderFor(contentType);
-        let text = '';
-        let bytesRead = 0;
-        try {
-            while (true) {
-                // response.body's stream type doesn't resolve here, so the chunk
-                // surfaces as `any`; pin it to the Uint8Array the reader yields.
-                const { value, done } = (await reader.read());
-                if (done)
-                    break;
-                if (value) {
-                    bytesRead += value.byteLength;
-                    if (bytesRead > maxBytes) {
-                        sizeExceeded = true;
-                        internalController.abort();
+            const contentType = response.headers.get('content-type') ?? '';
+            const kind = classifyContentType(contentType);
+            if (kind === 'reject') {
+                throw new FetchAndCleanError(`${url} is ${contentType || 'unknown content type'}, not a text or HTML page that pi-worker-fetch can read.`, 'not-html');
+            }
+            const reader = response.body?.getReader();
+            if (!reader) {
+                throw new FetchAndCleanError(`Could not fetch ${url}: empty response body`, 'network');
+            }
+            const decoder = decoderFor(contentType);
+            let text = '';
+            let bytesRead = 0;
+            try {
+                while (true) {
+                    // response.body's stream type doesn't resolve here, so the chunk
+                    // surfaces as `any`; pin it to the Uint8Array the reader yields.
+                    const { value, done } = (await reader.read());
+                    if (done)
                         break;
+                    if (value) {
+                        bytesRead += value.byteLength;
+                        if (bytesRead > maxBytes) {
+                            // OUR abort, told apart from the user's and the clock's
+                            // by the seam — all three abort the same signal.
+                            sizeExceeded = true;
+                            ctl.abort();
+                            break;
+                        }
+                        text += decoder.decode(value, { stream: true });
                     }
-                    text += decoder.decode(value, { stream: true });
                 }
+                text += decoder.decode();
             }
-            text += decoder.decode();
-        }
-        catch (err) {
-            if (sizeExceeded) {
-                // fall through to throw outside the catch
-            }
-            else if (userAborted) {
-                throw new FetchAndCleanError('Fetch aborted.', 'aborted', err);
+            catch (err) {
+                if (sizeExceeded) {
+                    // fall through to throw outside the catch
+                }
+                else if (ctl.userAborted()) {
+                    throw new FetchAndCleanError('Fetch aborted.', 'aborted', err);
+                }
+                else {
+                    throw new FetchAndCleanError(`Could not fetch ${url}: ${describeError(err)}`, 'network', err);
+                }
             }
-            else {
-                throw new FetchAndCleanError(`Could not fetch ${url}: ${describeError(err)}`, 'network', err);
+            if (sizeExceeded) {
+                throw new FetchAndCleanError(`${url} exceeds ${formatBytes(maxBytes)} size cap. Try a more specific URL.`, 'too-large');
             }
-        }
-        if (sizeExceeded) {
-            throw new FetchAndCleanError(`${url} exceeds ${formatBytes(maxBytes)} size cap. Try a more specific URL.`, 'too-large');
-        }
-        const finalUrl = response.url || url;
-        if (kind === 'html') {
-            return cleanHtml(text, finalUrl);
-        }
-        // text-ish formats are already clean — return them verbatim.
-        return {
-            title: hostnameOf(finalUrl),
-            markdown: text.trim(),
-            finalUrl
-        };
+            const finalUrl = response.url || url;
+            if (kind === 'html')
+                return cleanHtml(text, finalUrl);
+            // text-ish formats are already clean — return them verbatim.
+            return {
+                title: hostnameOf(finalUrl),
+                markdown: text.trim(),
+                finalUrl
+            };
+        });
     }
-    finally {
-        clearTimeout(timeoutHandle);
-        if (opts.signal)
-            opts.signal.removeEventListener('abort', onUserAbort);
+    catch (err) {
+        if (err instanceof HttpRequestError) {
+            throw err.kind === 'aborted' ?
+                new FetchAndCleanError('Fetch aborted.', 'aborted', err.cause)
+                : new FetchAndCleanError(`Could not fetch ${url}: ${err.detail}`, 'network', err.cause);
+        }
+        throw err;
     }
 }
 function hostnameOf(url) {
@@ -190,11 +174,6 @@ function hostnameOf(url) {
         return url;
     }
 }
-function describeError(err) {
-    if (err instanceof Error)
-        return err.message;
-    return String(err);
-}
 function formatBytes(n) {
     if (n >= 1024 * 1024)
         return `${(n / 1024 / 1024).toFixed(1)} MB`;