@mjasnikovs/pi-task 0.13.36 → 0.13.37

package/dist/workers/docs-core.js

@@ -4,7 +4,7 @@ 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 { resolvePackage as defaultResolvePackage, ResolveError, detectTypesRedirect, typesPackageName, hasTypeFiles, isDtsFile } 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';
@@ -44,6 +44,52 @@ export async function runAutoInstall(spawn, packageName, signal) {
     }, 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) {
+    try {
+        return resolvePackage(name, cwd);
+    }
+    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;
+        try {
+            return resolvePackage(name, install.installDir);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Follow the @types/<name> + triple-slash `<reference types>` redirect chain
+ *  from a package that ships no usable types of its own to the one that actually
+ *  holds the declarations (e.g. bun -> @types/bun -> bun-types). Bounded to a few
+ *  hops; returns the original package if no better source is found. */
+async function resolveTypeSource(pkg, requested, cwd, spawn, resolvePackage, signal) {
+    const visited = new Set([pkg.name, extractParentPackage(requested)]);
+    let cur = pkg;
+    for (let depth = 0; depth < 3; depth++) {
+        let next = detectTypesRedirect(cur);
+        if (next && visited.has(next))
+            next = null;
+        if (!next && !hasTypeFiles(cur.root)) {
+            const types = typesPackageName(cur.name);
+            if (types && !visited.has(types))
+                next = types;
+        }
+        if (!next)
+            break;
+        visited.add(next);
+        const resolved = await tryResolveOrInstall(next, cwd, spawn, resolvePackage, signal);
+        if (!resolved)
+            break;
+        cur = resolved;
+    }
+    return cur;
+}
 export async function docsRaw(input) {
     const resolvePackage = input.resolvePackage ?? defaultResolvePackage;
     const ensureIndexed = input.ensureIndexed ?? defaultEnsureIndexed;
@@ -114,6 +160,13 @@ export async function docsRaw(input) {
             };
         }
     }
+    // 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 resolveTypeSource(pkg, input.pkg, input.cwd, spawn, resolvePackage, input.signal);
     // Step 2: open cache
     let cache = null;
     let cacheError;
@@ -257,7 +310,7 @@ function walkDtsAlpha(root) {
             const full = path.join(dir, entry.name);
             if (entry.isDirectory())
                 stack.push(full);
-            else if (entry.isFile() && entry.name.endsWith('.d.ts'))
+            else if (entry.isFile() && isDtsFile(entry.name))
                 out.push(full);
         }
     }

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

@@ -1,5 +1,5 @@
 import type { CacheHandle } from './docs-cache.js';
-import type { ResolvedPackage } from './docs-resolve.js';
+import { type ResolvedPackage } from './docs-resolve.js';
 export interface IndexResult {
     hitCache: boolean;
     filesIngested: number;

package/dist/workers/docs-index.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { isDtsFile } from './docs-resolve.js';
 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;
@@ -48,13 +49,13 @@ function walkDts(root) {
                 const stat = fs.statSync(realPath);
                 if (stat.isDirectory())
                     stack.push(realPath);
-                else if (stat.isFile() && realPath.endsWith('.d.ts'))
+                else if (stat.isFile() && isDtsFile(realPath))
                     out.push(realPath);
                 continue;
             }
             if (entry.isDirectory())
                 stack.push(full);
-            else if (entry.isFile() && entry.name.endsWith('.d.ts'))
+            else if (entry.isFile() && isDtsFile(entry.name))
                 out.push(full);
         }
     }

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

@@ -1,3 +1,5 @@
+/** True for TypeScript declaration files: .d.ts, .d.mts, .d.cts. */
+export declare function isDtsFile(name: string): boolean;
 export interface ResolvedPackage {
     name: string;
     version: string;
@@ -10,3 +12,15 @@ export declare class ResolveError extends Error {
     constructor(kind: 'not_installed' | 'invalid_name', message: string);
 }
 export declare function resolvePackage(moduleName: string, cwd: string): ResolvedPackage;
+/** Conventional DefinitelyTyped package for a runtime package that ships no
+ *  types of its own. `bun` -> `@types/bun`, `@scope/x` -> `@types/scope__x`.
+ *  Returns null for packages that are already under the `@types` scope. */
+export declare function typesPackageName(moduleName: string): string | null;
+/** True if the package ships at least one declaration file. */
+export declare function hasTypeFiles(root: string): boolean;
+/** When a package is a pure pointer to another types package — a single-file
+ *  `/// <reference types="X" />` (the `@types/bun -> bun-types` shape) or a lone
+ *  `export * from "X"` re-export — return the target package name. Returns null
+ *  for packages that ship their own declarations (more than one .d.ts file, or a
+ *  local `/// <reference path=... />` aggregator entry). */
+export declare function detectTypesRedirect(pkg: ResolvedPackage): string | null;

package/dist/workers/docs-resolve.js

@@ -1,6 +1,11 @@
 import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+const DTS_RE = /\.d\.(?:ts|mts|cts)$/;
+/** True for TypeScript declaration files: .d.ts, .d.mts, .d.cts. */
+export function isDtsFile(name) {
+    return DTS_RE.test(name);
+}
 export class ResolveError extends Error {
     kind;
     constructor(kind, message) {
@@ -52,10 +57,18 @@ function findReadme(root) {
 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];
+        const candidates = [
+            `${subpath}.d.ts`,
+            `${subpath}.d.mts`,
+            `${subpath}.d.cts`,
+            `${subpath}/index.d.ts`,
+            `${subpath}/index.d.mts`,
+            `${subpath}/index.d.cts`,
+            subpath
+        ];
         for (const c of candidates) {
             const abs = path.join(root, c);
-            if (fs.existsSync(abs) && abs.endsWith('.d.ts'))
+            if (fs.existsSync(abs) && isDtsFile(abs))
                 return abs;
         }
     }
@@ -71,9 +84,11 @@ function resolveEntryDts(moduleName, parent, root, pkg) {
         if (fs.existsSync(abs))
             return abs;
     }
-    const fallback = path.join(root, 'index.d.ts');
-    if (fs.existsSync(fallback))
-        return fallback;
+    for (const name of ['index.d.ts', 'index.d.mts', 'index.d.cts']) {
+        const fallback = path.join(root, name);
+        if (fs.existsSync(fallback))
+            return fallback;
+    }
     return null;
 }
 export function resolvePackage(moduleName, cwd) {
@@ -124,3 +139,95 @@ function findPackageJsonInNodeModules(parent, startDir) {
         dir = up;
     }
 }
+/** Conventional DefinitelyTyped package for a runtime package that ships no
+ *  types of its own. `bun` -> `@types/bun`, `@scope/x` -> `@types/scope__x`.
+ *  Returns null for packages that are already under the `@types` scope. */
+export function typesPackageName(moduleName) {
+    const parent = parentPackageName(moduleName);
+    if (parent.startsWith('@types/'))
+        return null;
+    if (parent.startsWith('@')) {
+        const [scope, name] = parent.slice(1).split('/');
+        if (!scope || !name)
+            return null;
+        return `@types/${scope}__${name}`;
+    }
+    return `@types/${parent}`;
+}
+/** Count declaration files under root (excluding nested node_modules), stopping
+ *  once `cap` is reached. */
+function countTypeFiles(root, cap) {
+    let n = 0;
+    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() && isDtsFile(entry.name)) {
+                if (++n >= cap)
+                    return n;
+            }
+        }
+    }
+    return n;
+}
+/** True if the package ships at least one declaration file. */
+export function hasTypeFiles(root) {
+    return countTypeFiles(root, 1) > 0;
+}
+function findIndexDts(root) {
+    for (const name of ['index.d.ts', 'index.d.mts', 'index.d.cts']) {
+        const abs = path.join(root, name);
+        if (fs.existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+function isBareSpecifier(spec) {
+    return spec.length > 0 && !spec.startsWith('.') && !spec.startsWith('/');
+}
+const REFERENCE_TYPES_RE = /\/\/\/\s*<reference\s+types=["']([^"']+)["']\s*\/>/;
+const REEXPORT_ALL_RE = /^\s*export\s+(?:type\s+)?\*\s+from\s+["']([^"']+)["'];?\s*$/m;
+/** When a package is a pure pointer to another types package — a single-file
+ *  `/// <reference types="X" />` (the `@types/bun -> bun-types` shape) or a lone
+ *  `export * from "X"` re-export — return the target package name. Returns null
+ *  for packages that ship their own declarations (more than one .d.ts file, or a
+ *  local `/// <reference path=... />` aggregator entry). */
+export function detectTypesRedirect(pkg) {
+    // A package that ships multiple declaration files is an aggregator, not a
+    // redirect stub — use its own types.
+    if (countTypeFiles(pkg.root, 2) > 1)
+        return null;
+    const entry = pkg.entryDts ?? findIndexDts(pkg.root);
+    if (!entry)
+        return null;
+    let content;
+    try {
+        content = fs.readFileSync(entry, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    // A local `/// <reference path="..." />` means the entry aggregates sibling
+    // declarations (e.g. bun-types) — not a redirect to another package.
+    if (/\/\/\/\s*<reference\s+path=/.test(content))
+        return null;
+    const ref = REFERENCE_TYPES_RE.exec(content);
+    if (ref && isBareSpecifier(ref[1]))
+        return parentPackageName(ref[1]);
+    const rex = REEXPORT_ALL_RE.exec(content);
+    if (rex && isBareSpecifier(rex[1]))
+        return parentPackageName(rex[1]);
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.13.36",
+    "version": "0.13.37",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",