@mjasnikovs/pi-task 0.39.5 → 0.40.0

package/README.md

@@ -191,12 +191,25 @@ Fetches a URL, cleans HTML to markdown ([Readability](https://github.com/mozilla
 - The extraction child runs with `--no-tools` to mitigate visible-text prompt injection.
 
 ### `pi-worker-docs`
-Resolves an installed npm package, indexes its `.d.ts` files and README into a local SQLite cache, retrieves the most relevant chunks for your `query`, and passes them to an isolated child that extracts the focused answer. Version-pinned to whatever is in your `node_modules`.
+Resolves an installed package, indexes its API surface and README into a local SQLite cache, retrieves the most relevant chunks for your `query`, and passes them to an isolated child that extracts the focused answer. Version-pinned to whatever the project actually resolved.
 
-- The package must be installed in the project's `node_modules`; otherwise a one-time auto-install into a dedicated cache dir is attempted.
-- The first call for a `(package, version)` pair pays a one-time ingestion cost; later calls are FTS-only.
+**The manifest decides which registry, not the model.** `text`, `base`, `aeson`, `tokio` and `clap` are all real npm packages *and* real Rust/Haskell ones, so a name alone cannot say which was meant — and guessing npm returns a confident answer about an unrelated package. That is a wrong answer, not a miss.
+
+| Ecosystem | Detected by | Surface read | Version comes from |
+| --- | --- | --- | --- |
+| `npm` | `package.json`, or a `node_modules/` directory | the `.d.ts` files the package ships, plus README | the installed `package.json` |
+| `cargo` | `Cargo.toml`, at the directory or one level below it | `.rs` source reduced to public item heads, doc comments and attributes | `Cargo.lock` |
+| `hackage` | `*.cabal`, `cabal.project`, `stack.yaml` or `package.yaml` | `.hs` source reduced to the export list, signatures and type declarations | `dist-newstyle/cache/plan.json`, then `cabal.project.freeze`, then `stack.yaml.lock` |
+
+- **No manifest, no lookup.** In a directory with none of the above the tool refuses, spawns nothing and installs nothing, and points you at `pi-worker-search` / `pi-worker-fetch` instead.
+- **Two manifests** (a Tauri app, say) are resolved by whichever registry already has the package on disk. If neither does, the call is refused as ambiguous and you pass `ecosystem: "cargo"` to say which.
+- A package the project does not have is fetched once into a dedicated cache dir: `npm install --ignore-scripts` for npm, the `.crate` tarball for cargo, the Hackage tarball (or cabal's own cached copy) for hackage.
+- A Haskell **module** name is refused by name — `Data.Aeson` is not a package, `aeson` is.
+- The first call for a `(ecosystem, package, version)` triple pays a one-time ingestion cost; later calls are FTS-only.
 - Cache lives at `${XDG_CACHE_HOME:-~/.cache}/pi-worker/docs.sqlite` — delete it to reset.
 
+**Known gaps.** The rest of pi-task is still npm-shaped: the final gate, repo-health and orientation read the working directory first-wins, so a Tauri repo gets cargo docs answers while the gate runs `bun run test`, not `cargo test`. Phantom-import checking, dependency-name extraction for research enrichment, and the `@types/…` redirect chain are npm concepts and are no-ops elsewhere. Adding an ecosystem is one row in `src/workers/docs-ecosystems.ts` plus its parsers — profiles live in code and arrive as pull requests with tests, never as user configuration.
+
 ## Settings — `/task-config`
 
 Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings persist to `~/.config/pi-task/config.json`.
@@ -226,6 +239,8 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | --- | --- | --- |
 | `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required only when the **Brave** search engine is selected in `/task-config`. |
 | `XDG_CACHE_HOME` | `pi-worker-docs` | Overrides the docs cache location (defaults to `~/.cache`). |
+| `CARGO_HOME` | `pi-worker-docs` | Where crate source checkouts are read from (defaults to `~/.cargo`). |
+| `CABAL_DIR` | `pi-worker-docs` | Where cabal's downloaded package tarballs are read from (also checks `~/.cabal/packages` and `${XDG_CACHE_HOME:-~/.cache}/cabal/packages`). |
 | `XDG_DATA_HOME` | remote push | Where the VAPID keypair is stored (defaults to `~/.local/share`). |
 | `PI_REMOTE_PUSH_SUBJECT` | remote push | VAPID JWT `sub` contact. Defaults to the project URL; set your own `mailto:you@domain.com` or `https://…`. |
 | `PI_REMOTE_PUSH_DEBUG` | remote push | When set (e.g. `1`), logs push delivery and push-service HTTP status. Off by default. |

package/dist/task/context-attribution.js

@@ -154,17 +154,29 @@ export function splitBulletSpans(context) {
 export function splitBullets(context) {
     return splitBulletSpans(context).map(s => s.text);
 }
+/**
+ * A version block is headed by its REGISTRY, so the heading is open-ended
+ * (`crates.io`, `hackage`). Anything else is one: the widened pattern also reads
+ * headings out of a retrieved README or page BODY, and calling those `docs` would
+ * let a package's own text forge the block that sources a semantics claim.
+ */
+function blockKind(heading) {
+    if (heading === 'freshness-check')
+        return 'freshness-skipped';
+    if (heading === 'docs' || heading === 'url' || heading === 'service')
+        return heading;
+    return 'npm';
+}
 /** Parse the `### npm:` / `### docs:` / `### url:` / `### service:` blocks out of an EXTERNAL CONTEXT header. */
 export function parseContextBlocks(externalContext) {
     const out = [];
-    const re = /^###\s+(npm|docs|url|service|freshness-check)\s*:?\s*(.*)$/gim;
+    // A version block is headed by its REGISTRY, so `npm` is one of several
+    // (`crates.io`, `hackage`). Matching only the fixed words made every non-npm
+    // block invisible to the parser.
+    const re = /^###\s+([A-Za-z][\w.-]*)\s*:?\s*(.*)$/gim;
     let m;
     while ((m = re.exec(externalContext)) !== null) {
-        const kind = m[1].toLowerCase();
-        out.push({
-            kind: kind === 'freshness-check' ? 'freshness-skipped' : kind,
-            subject: m[2].trim()
-        });
+        out.push({ kind: blockKind(m[1].toLowerCase()), subject: m[2].trim() });
     }
     return out;
 }

package/dist/task/external-context.d.ts

@@ -36,6 +36,8 @@ type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep' | 'docsRaw'
 export interface ExternalTargetResult {
     /** Emitted as an `### npm:` block ahead of every body. Absent for url targets. */
     npmVersion?: NpmVersionInfo | null;
+    /** Which registry the version block came from; npm when absent. */
+    registryLabel?: string;
     /**
      * The `### docs:`/`### url:` body. `undefined` means "this target contributes no
      * body block" — and the two call paths draw that line differently ON PURPOSE:
@@ -68,6 +70,11 @@ export interface ExternalContextLookups {
  * question, in front of a waiting user, while research is uncapped and trails its
  * sub-step.
  */
+/** A live version answer and the registry it came from, for the block heading. */
+export interface VersionBlock {
+    info: NpmVersionInfo;
+    label: string;
+}
 export interface ExternalContextPolicy {
     /**
      * Max combined docs+url targets fanned out, packages first. Omit for uncapped
@@ -83,7 +90,7 @@ export interface ExternalContextPolicy {
      * version at all, and a "which version?" question falls back to whatever the
      * model remembers — which is how a dependency gets pinned to a stale major.
      */
-    versionLookup?: (pkg: string) => Promise<NpmVersionInfo | null>;
+    versionLookup?: (pkg: string) => Promise<VersionBlock | null>;
     /** Sub-step label recorded via `deps.recordSubStep`. Omit to record nothing. */
     subStepLabel?: string;
     /**

package/dist/task/external-context.js

@@ -22,6 +22,7 @@
  * Run against a mixed source, the emitted headings come out in exactly that order:
  * `### npm:` then `### docs:` then `### url:` then `### service:`.
  */
+import { chooseEcosystem, defaultEcosystemIo } from '../workers/docs-ecosystems.js';
 import { docsRaw } from '../workers/docs-core.js';
 import { fetchRaw } from '../workers/fetch-core.js';
 import { formatNpmVersionSection, npmVersionLookup } from '../workers/npm-version.js';
@@ -61,6 +62,14 @@ export async function buildExternalContext(source, deps, lookups, policy = {}) {
         }).catch(() => null))),
         Promise.all(versionLookup ? extraVersionPkgs.map(pkg => versionLookup(pkg).catch(() => null)) : [])
     ]);
+    // A docs target that came back WITHOUT a version — a refused ecosystem, a dead
+    // registry — was dropped from `extraVersionPkgs` on the assumption docs would
+    // supply it. Ask for it now, or its block is silently lost.
+    const missedVersionPkgs = versionLookup ?
+        enrichTargets.versionPackages.filter(p => docsTargets.has(p)
+            && !targets.some((t, i) => t.name === p && targetResults[i]?.npmVersion))
+        : [];
+    const missedVersionResults = await Promise.all(missedVersionPkgs.map(pkg => versionLookup(pkg).catch(() => null)));
     const sections = [];
     // npm version blocks lead the section so the model anchors on live version
     // data before reading any docs body. The docs-fetched packages carry their
@@ -69,11 +78,11 @@ export async function buildExternalContext(source, deps, lookups, policy = {}) {
     // named dep.
     for (const r of targetResults) {
         if (r?.npmVersion)
-            sections.push(formatNpmVersionSection(r.npmVersion));
+            sections.push(formatNpmVersionSection(r.npmVersion, r.registryLabel));
     }
-    for (const v of extraVersionResults) {
+    for (const v of [...extraVersionResults, ...missedVersionResults]) {
         if (v)
-            sections.push(formatNpmVersionSection(v));
+            sections.push(formatNpmVersionSection(v.info, v.label));
     }
     for (let i = 0; i < targets.length; i++) {
         const body = targetResults[i]?.body;
@@ -118,6 +127,44 @@ export async function gatherExternalContext(refined, deps) {
     const fetchRawFn = deps.fetchRaw ?? fetchRaw;
     const npmVersionFn = deps.npmVersionLookup ?? npmVersionLookup;
     const docsQuery = refined.split('\n').find(l => l.trim()) ?? refined;
+    // Which registry to ask, decided PER PACKAGE.
+    //
+    // A cargo-only project's dependency names are crate names, and asking npm
+    // about them returns a real but unrelated package's versions — the exact
+    // confusion the docs tool refuses. But deciding once for the whole repo makes
+    // every polyglot project ambiguous, and then NO version block is emitted at
+    // all: worse than the old always-npm, because the prompts tell the model to
+    // quote a block that will never be there. Each name carries its own evidence,
+    // so each name gets its own answer.
+    const io = defaultEcosystemIo(deps.signal ? { signal: deps.signal } : {});
+    const askNpm = async (pkg) => {
+        const info = await npmVersionFn(pkg, { signal: deps.signal });
+        return info ? { info, label: 'npm' } : null;
+    };
+    const versionLookup = async (pkg) => {
+        const choice = chooseEcosystem({
+            cwd: deps.cwd,
+            declaresPackage: p => p.declaredRange(p.parentPackage(pkg), deps.cwd) !== null,
+            resolvesLocally: p => {
+                try {
+                    p.resolve(pkg, deps.cwd, io);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+        });
+        // No manifest at all keeps npm, which is what a bare directory has always
+        // done. A name genuinely ambiguous between two registries gets no block —
+        // a version from the wrong registry is worse than none.
+        if (!choice.ok)
+            return choice.reason === 'none' ? askNpm(pkg) : null;
+        if (choice.profile.id === 'npm')
+            return askNpm(pkg);
+        const info = await choice.profile.latest(pkg, io);
+        return info ? { info, label: choice.profile.registryLabel } : null;
+    };
     return buildExternalContext(refined, deps, {
         docs: async (pkg) => {
             const r = await docsRawFn({
@@ -128,6 +175,7 @@ export async function gatherExternalContext(refined, deps) {
             });
             return {
                 npmVersion: r.npmVersion,
+                ...(r.registryLabel ? { registryLabel: r.registryLabel } : {}),
                 body: r.kind === 'ok' && r.chunks.length > 0 ?
                     r.chunks
                         .map(c => c.content)
@@ -142,7 +190,7 @@ export async function gatherExternalContext(refined, deps) {
         },
         search: deps.searchFn
     }, {
-        versionLookup: pkg => npmVersionFn(pkg, { signal: deps.signal }),
+        versionLookup,
         subStepLabel: 'enrichment',
         earlyReturnOnNoTargets: true
     });

package/dist/task/phases.js

@@ -4,6 +4,7 @@
  */
 import { fileURLToPath } from 'node:url';
 import { docsFocused } from '../workers/docs-core.js';
+import { detectEcosystems } from '../workers/docs-ecosystems.js';
 import { fetchFocused } from '../workers/fetch-core.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
@@ -550,7 +551,7 @@ export async function phaseResearch(deps, refined) {
             // queries the FILES worker just answered.
             prompt: prior => orientation.block
                 + promptHeader
-                + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined)
+                + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined, detectEcosystems(deps.cwd))
                 + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')
                 // Empty unless PI_TASK_PROJECT_DOCS_BUDGET is set. The tool-side
                 // half lives in pi-worker-docs.ts; a budget enforced without being

package/dist/task/prompts.d.ts

@@ -26,7 +26,13 @@ export declare const COMPRESS_LABEL_PROMPT: (title: string, maxChars: number) =>
 declare const REFINE_PROMPT: (raw: string, planContext?: string, existingFiles?: string, contracts?: string, directives?: string) => string;
 declare const RESEARCH_READ_ONLY_CONSTRAINT = "IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.";
 declare const RESEARCH_FILES_PROMPT: (refined: string) => string;
-declare const RESEARCH_APIS_PROMPT: (refined: string, filesMap?: string) => string;
+/**
+ * `ecosystems` is what `detectEcosystems` found in the worker's cwd. It is REQUIRED,
+ * and an empty list is a real answer: a directory with no package manifest has no
+ * registry to look a library up in, and the paragraph below has to say so rather
+ * than inviting a lookup that will be refused.
+ */
+declare const RESEARCH_APIS_PROMPT: (refined: string, filesMap: string | undefined, ecosystems: readonly string[]) => string;
 declare const RESEARCH_CONTEXT_PROMPT: (refined: string) => string;
 declare const RESEARCH_TOOLING_PROMPT: (refined: string) => string;
 declare const GRILL_GEN_PROMPT: (refined: string, research: string, priorQA: string) => string;

package/dist/task/prompts.js

@@ -97,13 +97,23 @@ No section header. No other sections. No preamble.
 
 Task:
 ${refined}`;
-const RESEARCH_APIS_PROMPT = (refined, filesMap) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools — and \`pi-worker-docs\` for installed npm packages — to identify the commands, functions, types, and interfaces the agent will use for the following task.
+/**
+ * `ecosystems` is what `detectEcosystems` found in the worker's cwd. It is REQUIRED,
+ * and an empty list is a real answer: a directory with no package manifest has no
+ * registry to look a library up in, and the paragraph below has to say so rather
+ * than inviting a lookup that will be refused.
+ */
+const RESEARCH_APIS_PROMPT = (refined, filesMap, ecosystems) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools${ecosystems.length ? ' — and `pi-worker-docs` for installed packages —' : ''} to identify the commands, functions, types, and interfaces the agent will use for the following task.
 
-NPM PACKAGES — use pi-worker-docs, NOT file reads: for any third-party npm package (e.g. "zod", "hono", "drizzle-orm"), call \`pi-worker-docs(module, query)\` to get its type signatures and API surface. Do NOT open node_modules source files directly — those reads are expensive and produce far more noise than the tool. The tool returns a compact, focused excerpt in a fraction of the token cost.
+${ecosystems.length ?
+    `LIBRARY PACKAGES — use pi-worker-docs, NOT file reads: for any third-party package, call \`pi-worker-docs(module, query)\` to get its type signatures and API surface. Do NOT open installed-package source files directly — those reads are expensive and produce far more noise than the tool. The tool returns a compact, focused excerpt in a fraction of the token cost. This project's package ecosystems are: ${ecosystems.join(', ')}.`
+    : 'LIBRARY PACKAGES — do NOT look them up: this directory holds no package manifest, so `pi-worker-docs` has no registry to read and will refuse. Do not list an external library API you cannot check here.'}
 
-PROJECT SOURCE — use pi-worker-docs with module ".", NOT file reads: for any function, class, type, or interface defined in THIS project's own .ts/.tsx source (e.g. "what does requireAuth check?", "what does CreateListingSchema look like?", "what does the listings query module export?"), call \`pi-worker-docs(".", query)\` instead of reading the file. The tool indexes all git-tracked source files and returns only the relevant chunks — far cheaper than reading whole files.
+PROJECT SOURCE — use pi-worker-docs with module ".", NOT file reads: for any function, class, type, or interface defined in THIS project's own source (e.g. "what does requireAuth check?", "what does CreateListingSchema look like?", "what does the listings query module export?"), call \`pi-worker-docs(".", query)\` instead of reading the file. The tool indexes all git-tracked source files and returns only the relevant chunks — far cheaper than reading whole files.
 
-RUNTIME BUILTINS — verify, do NOT echo: a task (or the spec doc it references) may name a runtime/builtin import like \`bun:sql\`, \`bun:sqlite\`, \`node:fs\`, or \`Bun.password\`. A runtime exposes only a small FIXED set of \`<runtime>:<submodule>\` modules, and a spec doc can confidently name one that does not exist. Before you list ANY \`<pkg>:<sub>\` specifier, confirm it with \`pi-worker-docs\` (e.g. \`pi-worker-docs("bun:sql", "sql tagged template and SQL class — the import")\` — the tool resolves the runtime's real types) and emit the CANONICAL import the types actually prove, NOT the string copied from the task. Concretely: Bun's SQL client is \`import { sql } from "bun"\` (or \`Bun.sql\` / \`new SQL()\`) — there is NO \`bun:sql\` module. Never pass an unverified colon-specifier through to the APIS list; a phantom import laundered here becomes fabricated \`declare module\` shims in the implementation.
+${ecosystems.includes('npm') ?
+    `RUNTIME BUILTINS — verify, do NOT echo: a task (or the spec doc it references) may name a runtime/builtin import like \`bun:sql\`, \`bun:sqlite\`, \`node:fs\`, or \`Bun.password\`. A runtime exposes only a small FIXED set of \`<runtime>:<submodule>\` modules, and a spec doc can confidently name one that does not exist. Before you list ANY \`<pkg>:<sub>\` specifier, confirm it with \`pi-worker-docs\` (e.g. \`pi-worker-docs("bun:sql", "sql tagged template and SQL class — the import")\` — the tool resolves the runtime's real types) and emit the CANONICAL import the types actually prove, NOT the string copied from the task. Concretely: Bun's SQL client is \`import { sql } from "bun"\` (or \`Bun.sql\` / \`new SQL()\`) — there is NO \`bun:sql\` module. Never pass an unverified colon-specifier through to the APIS list; a phantom import laundered here becomes fabricated \`declare module\` shims in the implementation.`
+    : ''}
 
 APIS owns symbols and commands BY NAME ONLY. Do NOT include any file path or path fragment — no \`package.json\`, no \`./src/foo.ts\`, no \`package.json#scripts.lint\`. If the symbol is a script defined in package.json, write the invocation (\`npm run lint\`), not its location. If the symbol is a config file, it does not belong in APIS at all — it belongs in FILES.
 

package/dist/workers/docs-cache.js

@@ -2,24 +2,37 @@ import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+/**
+ * Bump whenever the shape below changes in a way old rows cannot satisfy. The
+ * migration is a DROP and rebuild: this is a derived cache of package sources,
+ * so re-indexing costs a walk, and hand-written ALTERs cost a defect class.
+ */
+const SCHEMA_VERSION = 1;
+/**
+ * `ecosystem` scopes every row to the registry it came from, so `text` on npm and
+ * `text` on Hackage are different packages. Project-source rows use their own
+ * scope value rather than a registry id.
+ */
 const SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS packages (
+  ecosystem    TEXT NOT NULL DEFAULT 'npm',
   name         TEXT NOT NULL,
   version      TEXT NOT NULL,
   content_hash TEXT NOT NULL,
   indexed_at   INTEGER NOT NULL,
-  PRIMARY KEY (name, version)
+  PRIMARY KEY (ecosystem, name, version)
 );
 
 CREATE TABLE IF NOT EXISTS chunks (
   id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  ecosystem TEXT NOT NULL DEFAULT 'npm',
   name      TEXT NOT NULL,
   version   TEXT NOT NULL,
   file_path TEXT NOT NULL,
   kind      TEXT NOT NULL CHECK (kind IN ('dts','readme')),
   content   TEXT NOT NULL
 );
-CREATE INDEX IF NOT EXISTS chunks_pkg ON chunks(name, version);
+CREATE INDEX IF NOT EXISTS chunks_pkg ON chunks(ecosystem, name, version);
 
 CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
   content,
@@ -34,6 +47,14 @@ CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
   INSERT INTO chunks_fts(chunks_fts, rowid, content) VALUES('delete', old.id, old.content);
 END;
 `;
+// Order matters: the triggers and the FTS index reference `chunks`.
+const DROP_SQL = `
+DROP TRIGGER IF EXISTS chunks_ai;
+DROP TRIGGER IF EXISTS chunks_ad;
+DROP TABLE IF EXISTS chunks_fts;
+DROP TABLE IF EXISTS chunks;
+DROP TABLE IF EXISTS packages;
+`;
 const req = createRequire(import.meta.url);
 // Branch on the RUNTIME, not on a try/catch: each builtin exists in exactly one
 // of them. Requiring `bun:sqlite` under node throws MODULE_NOT_FOUND, and
@@ -61,9 +82,35 @@ export function openCache(dbPath) {
     db.exec('PRAGMA journal_mode = WAL;');
     db.exec('PRAGMA synchronous = NORMAL;');
     db.exec('PRAGMA foreign_keys = ON;');
-    db.exec(SCHEMA_SQL);
+    // A blocking busy handler, not a tuned delay: research children open this
+    // cache concurrently, and the loser of the migration lock has to WAIT for the
+    // winner's COMMIT rather than throw SQLITE_BUSY on the spot. The bound only
+    // stops a wedged handle hanging the worker forever.
+    db.exec('PRAGMA busy_timeout = 30000;');
+    migrate(db);
     return {
         db,
         close: () => db.close()
     };
 }
+/**
+ * `CREATE TABLE IF NOT EXISTS` is a no-op against an older shape, so the version
+ * check has to run BEFORE it or a stale table survives untouched.
+ */
+function migrate(db) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const row = db.prepare('PRAGMA user_version').get();
+        // A brand-new database also reads 0, hence DROP ... IF EXISTS.
+        if ((row?.user_version ?? 0) < SCHEMA_VERSION) {
+            db.exec(DROP_SQL);
+            db.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+        }
+        db.exec(SCHEMA_SQL);
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+}

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

@@ -53,15 +53,18 @@ export declare function splitAtMatches(text: string, re: RegExp): string[];
  */
 export declare function sliceBytes(s: string, maxBytes: number): string[];
 /**
- * Chunk a declaration file (`.d.ts`, `.ts`, `.tsx`), one chunk per declaration,
- * each labelled with the file it came from.
+ * Chunk a declaration file, one chunk per declaration, each labelled with the
+ * file it came from.
  *
  * `relPath` is a MODEL-FACING label and is used exactly as given. docs-index.ts
  * normalises it to POSIX (`.replace(/\\/g, '/')`) so a package index is identical
  * across platforms; docs-project.ts passes `path.relative` through with the native
  * separator. It is never re-joined to the filesystem, so neither is wrong — this
  * leaves the choice with the caller that has a reason for it.
+ *
+ * `splitRe` and `commentPrefix` default to the TypeScript pair, which is what
+ * both the project corpus and npm packages are written in.
  */
-export declare function chunkDeclarations(content: string, relPath: string): string[];
+export declare function chunkDeclarations(content: string, relPath: string, splitRe?: RegExp, commentPrefix?: string): string[];
 /** Chunk a README, one chunk per top-level section, each labelled by heading. */
 export declare function chunkReadme(content: string): string[];

package/dist/workers/docs-chunk.js

@@ -90,22 +90,25 @@ export function sliceBytes(s, maxBytes) {
     return out;
 }
 /**
- * Chunk a declaration file (`.d.ts`, `.ts`, `.tsx`), one chunk per declaration,
- * each labelled with the file it came from.
+ * Chunk a declaration file, one chunk per declaration, each labelled with the
+ * file it came from.
  *
  * `relPath` is a MODEL-FACING label and is used exactly as given. docs-index.ts
  * normalises it to POSIX (`.replace(/\\/g, '/')`) so a package index is identical
  * across platforms; docs-project.ts passes `path.relative` through with the native
  * separator. It is never re-joined to the filesystem, so neither is wrong — this
  * leaves the choice with the caller that has a reason for it.
+ *
+ * `splitRe` and `commentPrefix` default to the TypeScript pair, which is what
+ * both the project corpus and npm packages are written in.
  */
-export function chunkDeclarations(content, relPath) {
+export function chunkDeclarations(content, relPath, splitRe = DECL_SPLIT_RE, commentPrefix = '//') {
     const chunks = [];
-    for (const part of splitAtMatches(content, new RegExp(DECL_SPLIT_RE.source, 'gm'))) {
+    for (const part of splitAtMatches(content, new RegExp(splitRe.source, 'gm'))) {
         const trimmed = part.trim();
         if (!trimmed)
             continue;
-        const prefixed = `// ${relPath}\n${trimmed}`;
+        const prefixed = `${commentPrefix} ${relPath}\n${trimmed}`;
         if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
             for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES))
                 chunks.push(slice);

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

@@ -1,5 +1,6 @@
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
+import { type EcosystemId, type EcosystemIo, type EcosystemProfile } from './docs-ecosystems.js';
 import { resolvePackage as defaultResolvePackage, type ResolvedPackage } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks, type RetrievedChunk } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup, type NpmVersionInfo } from './npm-version.js';
@@ -37,6 +38,8 @@ export type DocsRawResult = {
     autoInstalled?: boolean;
     autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
+    /** The registry the answer came from, for the block that leads it. */
+    registryLabel?: string;
 } | {
     kind: 'no_chunks';
     pkg: ResolvedPackage;
@@ -46,10 +49,12 @@ export type DocsRawResult = {
     autoInstalled?: boolean;
     autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
+    /** The registry the answer came from, for the block that leads it. */
+    registryLabel?: string;
 } | {
     kind: 'error';
     message: string;
-    resolveError?: 'not_installed' | 'invalid_name';
+    resolveError?: 'not_installed' | 'invalid_name' | 'unsupported_ecosystem' | 'ambiguous_ecosystem';
     installError?: string;
     version?: string;
     hitCache?: boolean;
@@ -57,11 +62,15 @@ export type DocsRawResult = {
     autoInstalled?: boolean;
     autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
+    /** The registry the answer came from, for the block that leads it. */
+    registryLabel?: string;
 };
 export interface DocsRawInput {
     pkg: string;
     query: string;
     cwd: string;
+    /** Which registry to read, for a repo holding more than one manifest. */
+    ecosystem?: EcosystemId;
     autoInstall?: boolean;
     resolvePackage?: typeof defaultResolvePackage;
     ensureIndexed?: typeof defaultEnsureIndexed;
@@ -69,6 +78,8 @@ export interface DocsRawInput {
     openCache?: typeof defaultOpenCache;
     spawn?: SpawnFn;
     npmVersionLookup?: typeof defaultNpmVersionLookup;
+    /** Overrides for the filesystem and network a non-npm row reaches through. */
+    io?: Partial<EcosystemIo>;
     signal?: AbortSignal;
 }
 export interface DocsFocusedResult {
@@ -162,7 +173,7 @@ export declare function findDeclaredRange(parentPkg: string, cwd: string): strin
  * `bun`, and cannot declare `bun-types`, so a sentence about what package.json
  * does or does not say has to be a sentence about `bun`.
  */
-export declare function buildVersionBanner(pin: AutoInstallPin | undefined, resolved: string, version: string, cwd: string): string;
+export declare function buildVersionBanner(pin: AutoInstallPin | undefined, resolved: string, version: string, cwd: string, profile?: EcosystemProfile): string;
 export declare function getDocsModulesDir(): string;
 export declare function ensureDocsModulesDir(dir: string): void;
 /**
@@ -207,8 +218,13 @@ export interface AcquireInput {
     name: string;
     cwd: string;
     spawn: SpawnFn;
-    resolvePackage: typeof defaultResolvePackage;
+    /** Overrides `profile.resolve` when given, for callers that inject a resolver. */
+    resolvePackage?: typeof defaultResolvePackage;
     signal: AbortSignal | undefined;
+    /** Which registry to acquire from. */
+    profile?: EcosystemProfile;
+    /** The row's filesystem and network reach. Built from `spawn` when absent. */
+    io?: EcosystemIo;
 }
 /**
  * Get a package onto disk and resolved: resolve from `cwd`, and on
@@ -231,6 +247,14 @@ export interface AcquireInput {
  * sites should differ only about WHETHER to install, never about HOW.
  */
 export declare function acquirePackage(input: AcquireInput): Promise<AcquireOutcome>;
+/** 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. */
+export declare function resolveTypeSourceForDocs(pkg: ResolvedPackage, requested: string, cwd: string, spawn: SpawnFn, resolvePackage: typeof defaultResolvePackage, signal: AbortSignal | undefined): Promise<{
+    pkg: ResolvedPackage;
+    installed: boolean;
+    pin?: AutoInstallPin;
+}>;
 export declare function docsRaw(input: DocsRawInput): Promise<DocsRawResult>;
 export declare function docsFocused(input: DocsFocusedInput): Promise<DocsFocusedResult>;
 export declare function buildPrompt(pkg: ResolvedPackage, query: string, content: string): string;