@mjasnikovs/pi-task 0.2.0

package/dist/workers/docs-core.js

@@ -0,0 +1,329 @@
+import { spawn as defaultSpawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { openCache as defaultOpenCache } from './docs-cache.js';
+import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
+import { resolvePackage as defaultResolvePackage, ResolveError } from './docs-resolve.js';
+import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
+import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
+import { getPiInvocation } from '../shared/pi-invocation.js';
+import { CHILD_BASE_ARGS, runChild } from '../shared/child-process.js';
+import { parseChildOutput, isExcerptInContent, formatResultText as formatResultTextShared } from '../shared/child-output.js';
+const DEFAULT_LIMIT = 8;
+const DEFAULT_BUDGET = 24_000;
+const NO_CACHE_HEAD = 25_000;
+const NO_CACHE_TAIL = 5_000;
+const NO_CACHE_TOTAL = NO_CACHE_HEAD + NO_CACHE_TAIL;
+const NO_CACHE_MARKER = '\n\n[...content continues, truncated...]\n\n';
+const CHILD_ARGS = [...CHILD_BASE_ARGS, '--no-tools'];
+export function extractParentPackage(moduleName) {
+    if (moduleName.startsWith('@')) {
+        const parts = moduleName.split('/');
+        return `${parts[0]}/${parts[1]}`;
+    }
+    return moduleName.split('/')[0];
+}
+export function getDocsModulesDir() {
+    const base = process.env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), '.cache');
+    return path.join(base, 'pi-worker', 'docs-modules');
+}
+export function ensureDocsModulesDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+    const pkgPath = path.join(dir, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+        fs.writeFileSync(pkgPath, '{"name":"pi-worker-docs-modules","private":true}\n', 'utf8');
+    }
+}
+export async function runAutoInstall(spawn, packageName, signal) {
+    const installDir = getDocsModulesDir();
+    ensureDocsModulesDir(installDir);
+    const result = await runChild(spawn, {
+        command: 'npm',
+        args: ['install', '--no-audit', '--no-fund', '--loglevel=error', packageName]
+    }, installDir, signal, { mode: 'text', discardStdout: true });
+    return { success: result.exitCode === 0 && !result.aborted, installDir, stderr: result.stderr };
+}
+export async function docsRaw(input) {
+    const resolvePackage = input.resolvePackage ?? defaultResolvePackage;
+    const ensureIndexed = input.ensureIndexed ?? defaultEnsureIndexed;
+    const retrieveChunks = input.retrieveChunks ?? defaultRetrieveChunks;
+    const openCache = input.openCache ?? defaultOpenCache;
+    const spawn = input.spawn ?? defaultSpawn;
+    const npmVersionLookup = input.npmVersionLookup ?? defaultNpmVersionLookup;
+    // Fire the npm registry lookup in parallel with resolve/index/retrieve.
+    // It returns null on any failure, so it never blocks the local pipeline.
+    const npmVersionPromise = npmVersionLookup(extractParentPackage(input.pkg), {
+        signal: input.signal
+    }).catch(() => null);
+    // Step 1: resolve package
+    let pkg;
+    let autoInstalled = false;
+    try {
+        pkg = resolvePackage(input.pkg, input.cwd);
+    }
+    catch (firstErr) {
+        if (firstErr instanceof ResolveError && firstErr.kind === 'not_installed') {
+            // auto-install
+            const parentPkg = extractParentPackage(input.pkg);
+            const installResult = await runAutoInstall(spawn, parentPkg, 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,
+                    npmVersion: await npmVersionPromise
+                };
+            }
+            autoInstalled = true;
+            try {
+                pkg = resolvePackage(input.pkg, installResult.installDir);
+            }
+            catch (retryErr) {
+                if (retryErr instanceof ResolveError) {
+                    return {
+                        kind: 'error',
+                        message: retryErr.message,
+                        resolveError: retryErr.kind,
+                        autoInstalled,
+                        npmVersion: await npmVersionPromise
+                    };
+                }
+                return {
+                    kind: 'error',
+                    message: `Could not resolve "${input.pkg}" after install: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`,
+                    autoInstalled,
+                    npmVersion: await npmVersionPromise
+                };
+            }
+        }
+        else if (firstErr instanceof ResolveError) {
+            return {
+                kind: 'error',
+                message: firstErr.message,
+                resolveError: firstErr.kind,
+                npmVersion: await npmVersionPromise
+            };
+        }
+        else {
+            return {
+                kind: 'error',
+                message: `Could not resolve "${input.pkg}": ${firstErr instanceof Error ? firstErr.message : String(firstErr)}`,
+                npmVersion: await npmVersionPromise
+            };
+        }
+    }
+    // Step 2: open cache
+    let cache = null;
+    let cacheError;
+    try {
+        cache = openCache();
+    }
+    catch (err) {
+        cacheError = err instanceof Error ? err.message : String(err);
+    }
+    const result = cache ?
+        docsRawCached(cache, pkg, input.query, ensureIndexed, retrieveChunks, autoInstalled)
+        : docsRawUncached(pkg, cacheError ?? 'unknown cache error', autoInstalled);
+    result.npmVersion = await npmVersionPromise;
+    return result;
+}
+function docsRawCached(cache, pkg, query, ensureIndexed, retrieveChunks, autoInstalled) {
+    let indexResult;
+    const t0 = Date.now();
+    try {
+        indexResult = ensureIndexed(cache, pkg);
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            message: `Indexing failed for ${pkg.name}@${pkg.version}: ${err instanceof Error ? err.message : String(err)}`,
+            version: pkg.version
+        };
+    }
+    const indexingMs = indexResult.hitCache ? undefined : Date.now() - t0;
+    const chunkCount = cache.db
+        .prepare('SELECT count(*) AS c FROM chunks WHERE name = ? AND version = ?')
+        .get(pkg.name, pkg.version)?.c ?? 0;
+    if (chunkCount === 0) {
+        return {
+            kind: 'no_chunks',
+            pkg,
+            hitCache: indexResult.hitCache,
+            indexedFiles: 0,
+            autoInstalled: autoInstalled ? true : undefined
+        };
+    }
+    let chunks;
+    try {
+        chunks = retrieveChunks(cache, {
+            name: pkg.name,
+            version: pkg.version,
+            query,
+            limit: DEFAULT_LIMIT,
+            contentBudget: DEFAULT_BUDGET
+        });
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            message: `Retrieval failed for ${pkg.name}@${pkg.version}: ${err instanceof Error ? err.message : String(err)}`,
+            version: pkg.version,
+            hitCache: indexResult.hitCache
+        };
+    }
+    if (chunks.length === 0) {
+        return {
+            kind: 'no_chunks',
+            pkg,
+            hitCache: indexResult.hitCache,
+            autoInstalled: autoInstalled ? true : undefined
+        };
+    }
+    return {
+        kind: 'ok',
+        pkg,
+        chunks,
+        hitCache: indexResult.hitCache,
+        indexingMs,
+        autoInstalled: autoInstalled ? true : undefined
+    };
+}
+function docsRawUncached(pkg, cacheError, autoInstalled) {
+    const parts = [];
+    const dtsFiles = walkDtsAlpha(pkg.root);
+    const entryFirst = pkg.entryDts ? [pkg.entryDts, ...dtsFiles.filter(f => f !== pkg.entryDts)] : dtsFiles;
+    for (const abs of entryFirst) {
+        let raw;
+        try {
+            raw = fs.readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const rel = path.relative(pkg.root, abs);
+        parts.push(`// ${rel}\n${raw}`);
+    }
+    if (pkg.readme) {
+        const rel = path.relative(pkg.root, pkg.readme);
+        try {
+            const raw = fs.readFileSync(pkg.readme, 'utf8');
+            parts.push(`<!-- README: ${rel} -->\n${raw}`);
+        }
+        catch {
+            // skip
+        }
+    }
+    const joined = parts.join('\n\n');
+    if (joined.length === 0) {
+        return {
+            kind: 'no_chunks',
+            pkg,
+            hitCache: false,
+            indexedFiles: 0,
+            cacheError,
+            autoInstalled: autoInstalled ? true : undefined
+        };
+    }
+    const truncated = truncateHeadTail(joined);
+    const chunks = [
+        { filePath: '<no-cache>', kind: 'dts', content: truncated, rank: 0 }
+    ];
+    return {
+        kind: 'ok',
+        pkg,
+        chunks,
+        hitCache: false,
+        cacheError,
+        autoInstalled: autoInstalled ? true : undefined
+    };
+}
+function walkDtsAlpha(root) {
+    const out = [];
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name === 'node_modules')
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                stack.push(full);
+            else if (entry.isFile() && entry.name.endsWith('.d.ts'))
+                out.push(full);
+        }
+    }
+    return out.sort();
+}
+function truncateHeadTail(s) {
+    if (s.length <= NO_CACHE_TOTAL)
+        return s;
+    return s.slice(0, NO_CACHE_HEAD) + NO_CACHE_MARKER + s.slice(s.length - NO_CACHE_TAIL);
+}
+export async function docsFocused(input) {
+    const spawn = input.spawn ?? defaultSpawn;
+    const rawResult = await docsRaw(input);
+    if (rawResult.kind === 'error') {
+        throw new Error(rawResult.message);
+    }
+    if (rawResult.kind === 'not_installed') {
+        throw new Error(`Package "${rawResult.pkg}" is not installed`);
+    }
+    if (rawResult.kind === 'no_chunks') {
+        throw new Error(`Package ${rawResult.pkg.name}@${rawResult.pkg.version} has no .d.ts files or README.`);
+    }
+    const { pkg, chunks, hitCache, indexingMs } = rawResult;
+    const concatenated = chunks.map(c => c.content).join('\n\n');
+    const prompt = buildPrompt(pkg, input.query, concatenated);
+    const invocation = getPiInvocation([...CHILD_ARGS, prompt]);
+    const child = await runChild(spawn, invocation, input.cwd, input.signal);
+    const parsed = parseChildOutput(child.stdout);
+    const excerptVerified = parsed.excerpt ? isExcerptInContent(parsed.excerpt, concatenated) : undefined;
+    return {
+        answer: parsed.answer,
+        excerpt: parsed.excerpt,
+        excerptVerified,
+        pkg,
+        version: pkg.version,
+        exitCode: child.exitCode,
+        aborted: child.aborted,
+        stderr: child.stderr,
+        hitCache,
+        indexingMs,
+        chunksRetrieved: chunks.length,
+        autoInstalled: rawResult.autoInstalled,
+        npmVersion: rawResult.npmVersion
+    };
+}
+export function buildPrompt(pkg, query, content) {
+    return (`You answer one question about an npm package, using only the provided content.\n`
+        + `\n`
+        + `Rules:\n`
+        + `1. Output ONLY two tags, in this order, with NO text outside them:\n`
+        + `   <answer>...your answer...</answer>\n`
+        + `   <excerpt>...verbatim quote from <package-content>...</excerpt>\n`
+        + `2. The <excerpt> MUST be copied character-for-character from <package-content>.\n`
+        + `   Do not paraphrase, translate, or summarise inside <excerpt>.\n`
+        + `3. Prefer type signatures, function declarations, and code blocks as evidence over prose.\n`
+        + `4. If the answer is unclear, ambiguous, or absent from <package-content>, write exactly:\n`
+        + `   <answer>unclear from this package</answer> and put the closest related text in <excerpt>.\n`
+        + `   Do not guess.\n`
+        + `5. Be terse. One short paragraph in <answer> max.\n`
+        + `\n`
+        + `<package>${pkg.name}@${pkg.version}</package>\n`
+        + `<question>${query}</question>\n`
+        + `<package-content>\n${content}\n</package-content>\n`);
+}
+// ─── Backward-compatible wrappers (thin — delegates to shared/) ─────────────
+/** Thin wrapper so existing callers using the pkg-based signature still work. */
+export function formatResultText(pkg, parsed, verified) {
+    return formatResultTextShared(`Per ${pkg.name}@${pkg.version}:`, parsed, verified);
+}

package/dist/workers/docs-index.d.ts

@@ -0,0 +1,9 @@
+import type { CacheHandle } from './docs-cache.js';
+import type { ResolvedPackage } from './docs-resolve.js';
+export interface IndexResult {
+    hitCache: boolean;
+    filesIngested: number;
+    chunksWritten: number;
+    contentHash: string;
+}
+export declare function ensureIndexed(cache: CacheHandle, pkg: ResolvedPackage): IndexResult;

package/dist/workers/docs-index.js

@@ -0,0 +1,200 @@
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const MAX_CHUNK_BYTES = 8 * 1024;
+const ZERO_SEP = Buffer.from([0]);
+const DECL_SPLIT_RE = /^(?:export\s+|declare\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|namespace|module|const|let|var|enum)\s+/m;
+const README_SPLIT_RE = /^#{1,2} /m;
+function computeContentHash(pkg) {
+    const hash = createHash('sha256');
+    hash.update(Buffer.from(`${pkg.name}@${pkg.version}`, 'utf8'));
+    hash.update(ZERO_SEP);
+    if (pkg.entryDts && fs.existsSync(pkg.entryDts)) {
+        hash.update(fs.readFileSync(pkg.entryDts));
+    }
+    hash.update(ZERO_SEP);
+    if (pkg.readme && fs.existsSync(pkg.readme)) {
+        hash.update(fs.readFileSync(pkg.readme));
+    }
+    return hash.digest('hex');
+}
+function walkDts(root) {
+    const out = [];
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name === 'node_modules')
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                let realPath;
+                try {
+                    realPath = fs.realpathSync(full);
+                }
+                catch {
+                    continue;
+                }
+                const relReal = path.relative(root, realPath);
+                if (relReal.startsWith('..'))
+                    continue;
+                const stat = fs.statSync(realPath);
+                if (stat.isDirectory())
+                    stack.push(realPath);
+                else if (stat.isFile() && realPath.endsWith('.d.ts'))
+                    out.push(realPath);
+                continue;
+            }
+            if (entry.isDirectory())
+                stack.push(full);
+            else if (entry.isFile() && entry.name.endsWith('.d.ts'))
+                out.push(full);
+        }
+    }
+    return out.sort();
+}
+function collectFiles(pkg) {
+    return {
+        dts: walkDts(pkg.root),
+        readme: pkg.readme
+    };
+}
+function chunkDts(content, relPath) {
+    const splits = splitAtMatches(content, new RegExp(DECL_SPLIT_RE.source, 'gm'));
+    const chunks = [];
+    for (const part of splits) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const prefixed = `// ${relPath}\n${trimmed}`;
+        if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
+            for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES)) {
+                chunks.push(slice);
+            }
+        }
+        else {
+            chunks.push(prefixed);
+        }
+    }
+    return chunks;
+}
+function chunkReadme(content) {
+    const splits = splitAtMatches(content, new RegExp(README_SPLIT_RE.source, 'gm'));
+    const chunks = [];
+    for (const part of splits) {
+        const trimmed = part.replace(/\s+$/, '');
+        if (!trimmed)
+            continue;
+        const headingMatch = /^(#{1,2}) (.+)$/m.exec(trimmed);
+        const heading = headingMatch ? headingMatch[2] : '(intro)';
+        const prefixed = `<!-- README: ${heading} -->\n${trimmed}`;
+        if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
+            for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES))
+                chunks.push(slice);
+        }
+        else {
+            chunks.push(prefixed);
+        }
+    }
+    return chunks;
+}
+function splitAtMatches(text, re) {
+    const parts = [];
+    let lastIndex = 0;
+    let m;
+    while ((m = re.exec(text))) {
+        if (m.index > lastIndex)
+            parts.push(text.slice(lastIndex, m.index));
+        lastIndex = m.index;
+        re.lastIndex = m.index + 1;
+    }
+    if (lastIndex < text.length)
+        parts.push(text.slice(lastIndex));
+    return parts.length ? parts : [text];
+}
+function sliceBytes(s, maxBytes) {
+    const out = [];
+    let buf = Buffer.from(s, 'utf8');
+    while (buf.length > maxBytes) {
+        const slice = buf.subarray(0, maxBytes).toString('utf8');
+        out.push(slice);
+        buf = buf.subarray(Buffer.byteLength(slice, 'utf8'));
+    }
+    if (buf.length)
+        out.push(buf.toString('utf8'));
+    return out;
+}
+function ingestBody(cache, pkg, contentHash) {
+    const inside = cache.db
+        .prepare('SELECT content_hash FROM packages WHERE name = ? AND version = ?')
+        .get(pkg.name, pkg.version);
+    if (inside && inside.content_hash === contentHash) {
+        return { hitCache: true, filesIngested: 0, chunksWritten: 0 };
+    }
+    cache.db.prepare('DELETE FROM chunks WHERE name = ? AND version = ?').run(pkg.name, pkg.version);
+    const files = collectFiles(pkg);
+    let chunksWritten = 0;
+    let filesIngested = 0;
+    const insertChunk = cache.db.prepare('INSERT INTO chunks (name, version, file_path, kind, content) VALUES (?, ?, ?, ?, ?)');
+    for (const abs of files.dts) {
+        const rel = path.relative(pkg.root, abs);
+        let raw;
+        try {
+            raw = fs.readFileSync(abs, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const chunks = chunkDts(raw, rel);
+        if (!chunks.length)
+            continue;
+        filesIngested++;
+        for (const c of chunks) {
+            insertChunk.run(pkg.name, pkg.version, rel, 'dts', c);
+            chunksWritten++;
+        }
+    }
+    if (files.readme) {
+        const rel = path.relative(pkg.root, files.readme);
+        const raw = fs.readFileSync(files.readme, 'utf8');
+        const chunks = chunkReadme(raw);
+        if (chunks.length) {
+            filesIngested++;
+            for (const c of chunks) {
+                insertChunk.run(pkg.name, pkg.version, rel, 'readme', c);
+                chunksWritten++;
+            }
+        }
+    }
+    cache.db
+        .prepare('INSERT OR REPLACE INTO packages (name, version, content_hash, indexed_at) VALUES (?, ?, ?, ?)')
+        .run(pkg.name, pkg.version, contentHash, Date.now());
+    return { hitCache: false, filesIngested, chunksWritten };
+}
+export function ensureIndexed(cache, pkg) {
+    const contentHash = computeContentHash(pkg);
+    const existing = cache.db
+        .prepare('SELECT content_hash FROM packages WHERE name = ? AND version = ?')
+        .get(pkg.name, pkg.version);
+    if (existing && existing.content_hash === contentHash) {
+        return { hitCache: true, filesIngested: 0, chunksWritten: 0, contentHash };
+    }
+    cache.db.exec('BEGIN IMMEDIATE');
+    let result;
+    try {
+        result = ingestBody(cache, pkg, contentHash);
+        cache.db.exec('COMMIT');
+    }
+    catch (err) {
+        cache.db.exec('ROLLBACK');
+        throw err;
+    }
+    return { ...result, contentHash };
+}

package/dist/workers/docs-resolve.d.ts

@@ -0,0 +1,12 @@
+export interface ResolvedPackage {
+    name: string;
+    version: string;
+    root: string;
+    entryDts: string | null;
+    readme: string | null;
+}
+export declare class ResolveError extends Error {
+    readonly kind: 'not_installed' | 'invalid_name';
+    constructor(kind: 'not_installed' | 'invalid_name', message: string);
+}
+export declare function resolvePackage(moduleName: string, cwd: string): ResolvedPackage;

package/dist/workers/docs-resolve.js

@@ -0,0 +1,126 @@
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export class ResolveError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'ResolveError';
+    }
+}
+const MODULE_NAME_RE = /^(?:@[a-z0-9-_.]+\/)?[a-z0-9-_.]+(?:\/[a-z0-9-_./]+)?$/i;
+function isValidModuleName(name) {
+    if (!name || name.includes('..') || name.startsWith('/'))
+        return false;
+    return MODULE_NAME_RE.test(name);
+}
+function parentPackageName(moduleName) {
+    if (moduleName.startsWith('@')) {
+        const parts = moduleName.split('/');
+        return `${parts[0]}/${parts[1]}`;
+    }
+    return moduleName.split('/')[0];
+}
+function readPackageJson(file) {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+function extractTypesFromExports(exports) {
+    if (!exports || typeof exports === 'string')
+        return null;
+    const root = exports['.'];
+    if (!root || typeof root !== 'object')
+        return null;
+    const r = root;
+    const t = r.types;
+    return typeof t === 'string' ? t : null;
+}
+function findReadme(root) {
+    const candidate = path.join(root, 'README.md');
+    if (fs.existsSync(candidate))
+        return candidate;
+    let entries;
+    try {
+        entries = fs.readdirSync(root);
+    }
+    catch {
+        return null;
+    }
+    const match = entries.find(e => e.toLowerCase() === 'readme.md');
+    return match ? path.join(root, match) : null;
+}
+function resolveEntryDts(moduleName, parent, root, pkg) {
+    if (moduleName !== parent) {
+        const subpath = moduleName.slice(parent.length + 1);
+        const candidates = [`${subpath}.d.ts`, `${subpath}/index.d.ts`, subpath];
+        for (const c of candidates) {
+            const abs = path.join(root, c);
+            if (fs.existsSync(abs) && abs.endsWith('.d.ts'))
+                return abs;
+        }
+    }
+    const fromTypes = pkg.types || pkg.typings;
+    if (fromTypes) {
+        const abs = path.resolve(root, fromTypes);
+        if (fs.existsSync(abs))
+            return abs;
+    }
+    const fromExports = extractTypesFromExports(pkg.exports);
+    if (fromExports) {
+        const abs = path.resolve(root, fromExports);
+        if (fs.existsSync(abs))
+            return abs;
+    }
+    const fallback = path.join(root, 'index.d.ts');
+    if (fs.existsSync(fallback))
+        return fallback;
+    return null;
+}
+export function resolvePackage(moduleName, cwd) {
+    if (!isValidModuleName(moduleName)) {
+        throw new ResolveError('invalid_name', `Invalid module name: "${moduleName}"`);
+    }
+    const parent = parentPackageName(moduleName);
+    // First try: use createRequire (works when package.json is exported)
+    const requireFromCwd = createRequire(path.join(cwd, '__pi-worker-docs-sentinel__'));
+    let pkgJsonPath = null;
+    try {
+        pkgJsonPath = requireFromCwd.resolve(`${parent}/package.json`);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'MODULE_NOT_FOUND' && code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+            throw err;
+        // Fall through to direct filesystem fallback below
+    }
+    // Second try: walk node_modules directly (handles packages that don't export package.json)
+    if (!pkgJsonPath) {
+        const direct = findPackageJsonInNodeModules(parent, cwd);
+        if (!direct) {
+            throw new ResolveError('not_installed', `Package "${parent}" is not installed in ${cwd}. Run \`npm install ${parent}\` (or \`bun add ${parent}\`) and retry.`);
+        }
+        pkgJsonPath = direct;
+    }
+    const root = path.dirname(pkgJsonPath);
+    const pkg = readPackageJson(pkgJsonPath);
+    return {
+        name: pkg.name ?? parent,
+        version: pkg.version ?? '0.0.0',
+        root,
+        entryDts: resolveEntryDts(moduleName, parent, root, pkg),
+        readme: findReadme(root)
+    };
+}
+function findPackageJsonInNodeModules(parent, startDir) {
+    const segments = parent.startsWith('@') ? parent.split('/').slice(0, 2) : [parent.split('/')[0]];
+    let dir = startDir;
+    while (true) {
+        const candidate = path.join(dir, 'node_modules', ...segments, 'package.json');
+        if (fs.existsSync(candidate))
+            return candidate;
+        const up = path.dirname(dir);
+        if (up === dir)
+            return null;
+        dir = up;
+    }
+}

package/dist/workers/docs-retrieve.d.ts

@@ -0,0 +1,15 @@
+import type { CacheHandle } from './docs-cache.js';
+export interface RetrievedChunk {
+    filePath: string;
+    kind: 'dts' | 'readme';
+    content: string;
+    rank: number;
+}
+export interface RetrieveOptions {
+    name: string;
+    version: string;
+    query: string;
+    limit?: number;
+    contentBudget?: number;
+}
+export declare function retrieveChunks(cache: CacheHandle, opts: RetrieveOptions): RetrievedChunk[];