@mjasnikovs/pi-task 0.10.3 → 0.12.0

package/dist/task/prompts.js

@@ -92,6 +92,8 @@ const RESEARCH_APIS_PROMPT = (refined) => `You are doing targeted research for a
 
 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.
 
+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.
+
 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.
 
 RELEVANCE — read carefully: list ONLY the symbols the agent will call, implement, modify, or directly depend on for THIS task. Do NOT enumerate the project's entire public surface or dump every exported function in a touched file. A symbol unrelated to the task does not belong here just because it sits in the same module. Keep the smallest sufficient set: include every symbol the task actually exercises and nothing more. There is no fixed limit — list as many as the task truly needs and no padding beyond that.

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

@@ -0,0 +1,38 @@
+import type { CacheHandle } from './docs-cache.js';
+import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
+import type { RetrievedChunk } from './docs-retrieve.js';
+export declare function getProjectName(cwd: string): string;
+export declare function cwdKey(cwd: string): string;
+export declare function getProjectFiles(cwd: string): string[];
+export declare function getMaxMtime(files: string[]): string;
+export interface ProjectIndexResult {
+    hitCache: boolean;
+    filesIngested: number;
+    chunksWritten: number;
+    indexingMs?: number;
+}
+export declare function ensureProjectIndexed(cache: CacheHandle, name: string, version: string, files: string[], cwd: string): ProjectIndexResult;
+export type ProjectDocsRawResult = {
+    kind: 'ok';
+    projectName: string;
+    cacheKey: string;
+    version: string;
+    chunks: RetrievedChunk[];
+    hitCache: boolean;
+    filesIngested: number;
+    chunksWritten: number;
+    indexingMs?: number;
+} | {
+    kind: 'no_chunks';
+    projectName: string;
+    cacheKey: string;
+    version: string;
+    hitCache: boolean;
+    filesIngested: number;
+} | {
+    kind: 'error';
+    projectName: string;
+    message: string;
+};
+export declare function projectDocsRaw(cache: CacheHandle, cwd: string, query: string, retrieveChunksFn?: typeof defaultRetrieveChunks): ProjectDocsRawResult;
+export declare function buildProjectPrompt(projectName: string, query: string, content: string): string;

package/dist/workers/docs-project.js

@@ -0,0 +1,249 @@
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
+const MAX_CHUNK_BYTES = 8 * 1024;
+const DEFAULT_LIMIT = 50;
+const DEFAULT_BUDGET = 24_000;
+const DECL_SPLIT_RE = /^(?:export\s+|declare\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|namespace|module|const|let|var|enum)\s+/m;
+export function getProjectName(cwd) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+        if (pkg.name)
+            return pkg.name;
+    }
+    catch { }
+    return path.basename(cwd);
+}
+export function cwdKey(cwd) {
+    return createHash('sha256').update(cwd).digest('hex').slice(0, 8);
+}
+export function getProjectFiles(cwd) {
+    try {
+        const result = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '*.ts', '*.tsx'], { cwd, encoding: 'utf8', timeout: 5000 });
+        if (result.status === 0 && result.stdout?.trim()) {
+            return result.stdout
+                .trim()
+                .split('\n')
+                .filter(Boolean)
+                .map(f => path.join(cwd, f));
+        }
+    }
+    catch { }
+    return walkTsFiles(cwd);
+}
+function walkTsFiles(root) {
+    const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+    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 (SKIP.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                stack.push(full);
+            else if (entry.isFile() &&
+                (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
+                out.push(full);
+            }
+        }
+    }
+    return out.sort();
+}
+export function getMaxMtime(files) {
+    let max = 0;
+    for (const f of files) {
+        try {
+            const { mtimeMs } = fs.statSync(f);
+            if (mtimeMs > max)
+                max = mtimeMs;
+        }
+        catch { }
+    }
+    return String(Math.floor(max));
+}
+function chunkTs(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 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;
+}
+export function ensureProjectIndexed(cache, name, version, files, cwd) {
+    const existing = cache.db
+        .prepare('SELECT content_hash FROM packages WHERE name = ? AND version = ?')
+        .get(name, version);
+    if (existing)
+        return { hitCache: true, filesIngested: 0, chunksWritten: 0 };
+    const t0 = Date.now();
+    cache.db.exec('BEGIN IMMEDIATE');
+    try {
+        // Clear all old versions of this project
+        cache.db.prepare('DELETE FROM chunks WHERE name = ?').run(name);
+        cache.db.prepare('DELETE FROM packages WHERE name = ?').run(name);
+        const insertChunk = cache.db.prepare('INSERT INTO chunks (name, version, file_path, kind, content) VALUES (?, ?, ?, ?, ?)');
+        let filesIngested = 0;
+        let chunksWritten = 0;
+        for (const abs of files) {
+            let raw;
+            try {
+                raw = fs.readFileSync(abs, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const rel = path.relative(cwd, abs);
+            const chunks = chunkTs(raw, rel);
+            if (!chunks.length)
+                continue;
+            filesIngested++;
+            for (const c of chunks) {
+                insertChunk.run(name, version, rel, 'dts', c);
+                chunksWritten++;
+            }
+        }
+        cache.db
+            .prepare('INSERT OR REPLACE INTO packages (name, version, content_hash, indexed_at) VALUES (?, ?, ?, ?)')
+            .run(name, version, version, Date.now());
+        cache.db.exec('COMMIT');
+        return { hitCache: false, filesIngested, chunksWritten, indexingMs: Date.now() - t0 };
+    }
+    catch (err) {
+        cache.db.exec('ROLLBACK');
+        throw err;
+    }
+}
+export function projectDocsRaw(cache, cwd, query, retrieveChunksFn = defaultRetrieveChunks) {
+    const projectName = getProjectName(cwd);
+    const cacheKey = `project:${cwdKey(cwd)}`;
+    const files = getProjectFiles(cwd);
+    const version = getMaxMtime(files);
+    let indexResult;
+    try {
+        indexResult = ensureProjectIndexed(cache, cacheKey, version, files, cwd);
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            projectName,
+            message: `Indexing failed: ${err instanceof Error ? err.message : String(err)}`
+        };
+    }
+    const chunkCount = cache.db
+        .prepare('SELECT count(*) AS c FROM chunks WHERE name = ? AND version = ?')
+        .get(cacheKey, version)?.c ?? 0;
+    if (chunkCount === 0) {
+        return {
+            kind: 'no_chunks',
+            projectName,
+            cacheKey,
+            version,
+            hitCache: indexResult.hitCache,
+            filesIngested: indexResult.filesIngested
+        };
+    }
+    let chunks;
+    try {
+        chunks = retrieveChunksFn(cache, {
+            name: cacheKey,
+            version,
+            query,
+            limit: DEFAULT_LIMIT,
+            contentBudget: DEFAULT_BUDGET
+        });
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            projectName,
+            message: `Retrieval failed: ${err instanceof Error ? err.message : String(err)}`
+        };
+    }
+    if (chunks.length === 0) {
+        return {
+            kind: 'no_chunks',
+            projectName,
+            cacheKey,
+            version,
+            hitCache: indexResult.hitCache,
+            filesIngested: indexResult.filesIngested
+        };
+    }
+    return {
+        kind: 'ok',
+        projectName,
+        cacheKey,
+        version,
+        chunks,
+        hitCache: indexResult.hitCache,
+        filesIngested: indexResult.filesIngested,
+        chunksWritten: indexResult.chunksWritten,
+        indexingMs: indexResult.indexingMs
+    };
+}
+export function buildProjectPrompt(projectName, query, content) {
+    return (`You answer one question about a local project's source code, 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 <project-content>...</excerpt>\n`
+        + `2. The <excerpt> MUST be copied character-for-character from <project-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 <project-content>, write exactly:\n`
+        + `   <answer>unclear from this project</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`
+        + `<project>${projectName}</project>\n`
+        + `<question>${query}</question>\n`
+        + `<project-content>\n${content}\n</project-content>\n`);
+}

package/dist/workers/docs-retrieve.js

@@ -1,4 +1,4 @@
-const DEFAULT_LIMIT = 8;
+const DEFAULT_LIMIT = 50;
 const DEFAULT_BUDGET = 24_000;
 const MIN_TOKEN_LEN = 2;
 const FALLBACK_DTS_CHARS = 12_000;

package/dist/workers/pi-worker-docs.js

@@ -1,19 +1,22 @@
 import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
+import { openCache as defaultOpenCache } from './docs-cache.js';
+import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { docsRaw, formatResultText, buildPrompt } from './docs-core.js';
 import { formatNpmVersionSection } from './npm-version.js';
 import { runChild, CHILD_BASE_ARGS } from '../shared/child-process.js';
 import { parseChildOutput, isExcerptInContent } from '../shared/child-output.js';
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { textResult } from './shared.js';
+import { projectDocsRaw, buildProjectPrompt } from './docs-project.js';
 const CHILD_ARGS = [...CHILD_BASE_ARGS, '--no-tools'];
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
     module: Type.String({
-        description: 'Bare npm module name (e.g. "zod", "@scope/name", "react/jsx-runtime"). Must be installed in the project\'s node_modules.'
+        description: 'Bare npm module name (e.g. "zod", "@scope/name", "react/jsx-runtime"), OR "." to look up the current project\'s own source code. npm packages must be installed in node_modules.'
     }),
     query: Type.String({
-        description: 'What to extract from the module\'s docs. The child pi reads ranked chunks and returns ONLY content answering this.'
+        description: 'What to extract from the docs. The child pi reads ranked chunks and returns ONLY content answering this.'
     })
 });
 export function registerPiWorkerDocs(pi, internals = {}) {
@@ -35,11 +38,20 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             + '~/.cache/pi-worker/docs.sqlite, keyed by exact installed version; the '
             + 'registry lookup is best-effort and silently absent when offline.\n'
             + '\n'
+            + 'Pass module: "." to look up the CURRENT PROJECT\'S OWN SOURCE CODE instead '
+            + 'of an npm package. USE THIS when asked about what a function, class, type, '
+            + 'or module in this project does or exports — e.g. "what does orchestrator.ts '
+            + 'export?", "how does the requireAuth middleware work?", "what props does '
+            + 'ListingCard accept?". The project source is indexed from git-tracked .ts/.tsx '
+            + 'files and cached by max file mtime — always reflects the current state of '
+            + 'the working tree.\n'
+            + '\n'
             + 'Good fits:\n'
             + '- "What does library X export?" / "How does function Y work?"\n'
             + '- Confirming generic shapes, overload sets, exported types\n'
             + '- Pulling README configuration prose without burning context on raw markdown\n'
             + '- Checking the current latest published version of a package\n'
+            + '- "What does src/X.ts export?" / "How does this project\'s Y function work?"\n'
             + '\n'
             + 'Skip when:\n'
             + '- You need docs for a specific newer version than what is installed — use pi-worker-fetch on the upstream docs site',
@@ -50,6 +62,65 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 ?? (globalThis.Bun !== undefined ?
                     globalThis.Bun.spawn
                     : (await import('node:child_process')).spawn);
+            // ── Project source lookup ───────────────────────────────────────
+            if (params.module === '.') {
+                const openCache = internals.openCache ?? defaultOpenCache;
+                let cache;
+                let cacheError;
+                try {
+                    cache = openCache();
+                }
+                catch (err) {
+                    cacheError = err instanceof Error ? err.message : String(err);
+                }
+                if (!cache) {
+                    return textResult(`Project docs unavailable: cache open failed (${cacheError}).`, {});
+                }
+                const retrieveChunks = internals.retrieveChunks ?? defaultRetrieveChunks;
+                const projectResult = projectDocsRaw(cache, ctx.cwd, params.query, retrieveChunks);
+                if (projectResult.kind === 'error') {
+                    return textResult(`Project docs error: ${projectResult.message}`, {});
+                }
+                if (projectResult.kind === 'no_chunks') {
+                    return textResult(`Project "${projectResult.projectName}" has no .ts/.tsx files indexed.`, { hitCache: projectResult.hitCache, indexedFiles: projectResult.filesIngested });
+                }
+                const { projectName, chunks, hitCache, filesIngested, indexingMs } = projectResult;
+                const baseDetails = {
+                    hitCache,
+                    chunksRetrieved: chunks.length,
+                    indexedFiles: filesIngested,
+                    indexingMs
+                };
+                const concatenated = chunks.map(c => c.content).join('\n\n');
+                const prompt = buildProjectPrompt(projectName, params.query, concatenated);
+                const invocation = getPiInvocation([...CHILD_ARGS, prompt]);
+                const child = await runChild(spawn, invocation, ctx.cwd, signal);
+                if (child.aborted) {
+                    return textResult('Project docs lookup aborted.', {
+                        ...baseDetails,
+                        aborted: true,
+                        childExitCode: child.exitCode
+                    });
+                }
+                if (child.exitCode !== 0) {
+                    const tail = child.stderr.trim().slice(-500) || '(no stderr)';
+                    return textResult(`Worker exited ${child.exitCode}.\n${tail}`, {
+                        ...baseDetails,
+                        childExitCode: child.exitCode
+                    });
+                }
+                const parsed = parseChildOutput(child.stdout);
+                const verified = parsed.excerpt ?
+                    isExcerptInContent(parsed.excerpt, concatenated)
+                    : undefined;
+                const text = formatResultText({ name: projectName, version: 'local', root: ctx.cwd, entryDts: null, readme: null }, parsed, verified);
+                return textResult(text, {
+                    ...baseDetails,
+                    childExitCode: 0,
+                    excerptVerified: verified
+                });
+            }
+            // ── npm package lookup (existing path) ──────────────────────────
             const rawResult = await docsRaw({
                 pkg: params.module,
                 query: params.query,
@@ -137,8 +208,9 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         renderCall(args, theme) {
             const query = args.query.replace(/\s+/g, ' ').trim();
             const truncated = query.length > RENDER_QUERY_MAX ? `${query.slice(0, RENDER_QUERY_MAX - 1)}…` : query;
+            const label = args.module === '.' ? 'project' : args.module;
             let text = theme.fg('toolTitle', theme.bold('pi-worker-docs '));
-            text += theme.fg('accent', args.module);
+            text += theme.fg('accent', label);
             text += `\n${theme.fg('dim', `  query: ${truncated}`)}`;
             return new Text(text, 0, 0);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.10.3",
+    "version": "0.12.0",
     "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",