@mjasnikovs/pi-task 0.2.0

package/dist/task/timings.js

@@ -0,0 +1,36 @@
+/**
+ * Phase timing data — captures how long each pipeline phase took so we can
+ * spot regressions and target future speed improvements.
+ *
+ * Top-level entries are the five phases (refine, research, grill, compose,
+ * critique). Each phase may attach optional sub-step children (e.g. research
+ * → workers + verify-tooling, grill → gen + auto-answers + user input).
+ *
+ * `formatTimings` produces the human-readable block we write to the
+ * `## phase timings` section of the TASK_NNNN.md file.
+ */
+const TOP_LABEL_WIDTH = 18;
+const SUB_LABEL_WIDTH = 20;
+const MS_COLUMN_WIDTH = 8;
+export function formatMs(ms) {
+    if (ms < 0)
+        ms = 0;
+    if (ms < 1000)
+        return `${ms}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+export function formatTimings(entries) {
+    if (entries.length === 0)
+        return '(no phases recorded)';
+    const lines = [];
+    let total = 0;
+    for (const e of entries) {
+        total += e.ms;
+        lines.push(`${e.label.padEnd(TOP_LABEL_WIDTH)}${formatMs(e.ms).padStart(MS_COLUMN_WIDTH)}`);
+        for (const c of e.children) {
+            lines.push(`  ${c.label.padEnd(SUB_LABEL_WIDTH)}${formatMs(c.ms).padStart(MS_COLUMN_WIDTH)}`);
+        }
+    }
+    lines.push(`${'total'.padEnd(TOP_LABEL_WIDTH)}${formatMs(total).padStart(MS_COLUMN_WIDTH)}`);
+    return lines.join('\n');
+}

package/dist/task/widget.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Terminal widget for the pi-task orchestrator.
+ *
+ * Renders a live-updating status block showing task id, phase, elapsed time,
+ * context usage, and the latest child-process line.
+ */
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { type PhaseName, type TaskState } from './task-file.js';
+export interface WidgetState {
+    taskId: string;
+    title: string;
+    phase: PhaseName;
+    startedAt: number;
+    lastLine?: string;
+    contextUsage?: ContextSnapshot;
+}
+export interface ContextSnapshot {
+    tokens: number;
+    contextWindow: number;
+    percent: number;
+}
+export type WidgetTheme = ExtensionCommandContext['ui']['theme'];
+export declare const WIDGET_KEY = "pi-tasks";
+export declare const WIDGET_REFRESH_MS = 500;
+export declare const WIDGET_LAST_LINE_MAX = 120;
+export declare const NOTIFY_CLEAR_MS = 3000;
+export declare const FAIL_CLEAR_MS = 4000;
+export declare const CTX_BAR_WIDTH = 8;
+export declare const CTX_BAR_FILLED = "\u2593";
+export declare const CTX_BAR_EMPTY = "\u2591";
+export declare const CTX_WARN_PERCENT = 80;
+export declare const CTX_ERROR_PERCENT = 90;
+export declare function formatDuration(ms: number): string;
+export declare function formatContextTokens(count: number): string;
+export declare function contextProgressBar(percent: number): string;
+export declare function contextThresholdColor(theme: WidgetTheme, percent: number, text: string): string;
+export declare function buildWidgetLines(s: WidgetState, theme?: WidgetTheme): string[];
+export declare function startWidget(ctx: ExtensionCommandContext, getState: () => WidgetState | null): () => void;
+export declare function flashTerminalWidget(ctx: ExtensionCommandContext, state: Exclude<TaskState, 'pending' | 'in_progress' | 'completed'>, taskId: string, reason: string | undefined): void;

package/dist/task/widget.js

@@ -0,0 +1,122 @@
+/**
+ * Terminal widget for the pi-task orchestrator.
+ *
+ * Renders a live-updating status block showing task id, phase, elapsed time,
+ * context usage, and the latest child-process line.
+ */
+import { PHASE_INDEX, PHASE_ORDER } from './task-file.js';
+// ─── Constants ───────────────────────────────────────────────────────────────
+export const WIDGET_KEY = 'pi-tasks';
+export const WIDGET_REFRESH_MS = 500;
+export const WIDGET_LAST_LINE_MAX = 120;
+export const NOTIFY_CLEAR_MS = 3000;
+export const FAIL_CLEAR_MS = 4000;
+export const CTX_BAR_WIDTH = 8;
+export const CTX_BAR_FILLED = '▓';
+export const CTX_BAR_EMPTY = '░';
+export const CTX_WARN_PERCENT = 80;
+export const CTX_ERROR_PERCENT = 90;
+// ─── Formatting helpers ──────────────────────────────────────────────────────
+export function formatDuration(ms) {
+    const total = Math.floor(ms / 1000);
+    const m = Math.floor(total / 60);
+    const s = total % 60;
+    return `${m}:${String(s).padStart(2, '0')}`;
+}
+export function formatContextTokens(count) {
+    if (count < 1_000)
+        return count.toString();
+    if (count < 10_000)
+        return `${(count / 1_000).toFixed(1)}k`;
+    if (count < 1_000_000)
+        return `${Math.round(count / 1_000)}k`;
+    if (count < 10_000_000)
+        return `${(count / 1_000_000).toFixed(1)}M`;
+    return `${Math.round(count / 1_000_000)}M`;
+}
+export function contextProgressBar(percent) {
+    const clamped = Math.max(0, Math.min(100, percent));
+    const filled = Math.round((clamped / 100) * CTX_BAR_WIDTH);
+    return `[${CTX_BAR_FILLED.repeat(filled)}${CTX_BAR_EMPTY.repeat(CTX_BAR_WIDTH - filled)}]`;
+}
+export function contextThresholdColor(theme, percent, text) {
+    if (percent >= CTX_ERROR_PERCENT)
+        return theme.fg('error', text);
+    if (percent >= CTX_WARN_PERCENT)
+        return theme.fg('warning', text);
+    return text;
+}
+export function buildWidgetLines(s, theme) {
+    const elapsed = formatDuration(Date.now() - s.startedAt);
+    const head = `${s.taskId} · ${s.title}`;
+    const idx = PHASE_INDEX[s.phase];
+    const total = PHASE_ORDER.length;
+    const stepNum = Math.min(idx + 1, total);
+    let detail = `phase ${stepNum}/${total} ${s.phase} · ${elapsed}`;
+    if (s.contextUsage) {
+        const { tokens, contextWindow, percent } = s.contextUsage;
+        if (contextWindow > 0) {
+            const text = `${formatContextTokens(tokens)}/${formatContextTokens(contextWindow)} ${contextProgressBar(percent)}`;
+            detail += ` · ${theme ? contextThresholdColor(theme, percent, text) : text}`;
+        }
+        else if (tokens > 0) {
+            detail += ` · ${formatContextTokens(tokens)}`;
+        }
+    }
+    const lines = [head, detail];
+    if (s.lastLine) {
+        const t = s.lastLine.length > WIDGET_LAST_LINE_MAX ?
+            s.lastLine.slice(0, WIDGET_LAST_LINE_MAX - 1) + '…'
+            : s.lastLine;
+        const raw = `↳ ${t}`;
+        lines.push(theme ? theme.fg('muted', raw) : raw);
+    }
+    return lines;
+}
+// ─── Widget lifecycle ────────────────────────────────────────────────────────
+export function startWidget(ctx, getState) {
+    if (!ctx.hasUI)
+        return () => { };
+    const render = () => {
+        const s = getState();
+        try {
+            ctx.ui.setWidget(WIDGET_KEY, s ? buildWidgetLines(s, ctx.ui.theme) : undefined);
+        }
+        catch {
+            /* stale ctx */
+        }
+    };
+    render();
+    const timer = setInterval(render, WIDGET_REFRESH_MS);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+export function flashTerminalWidget(ctx, state, taskId, reason) {
+    if (!ctx.hasUI)
+        return;
+    const theme = ctx.ui.theme;
+    let line;
+    let clearMs;
+    if (state === 'cancelled') {
+        line = theme.fg('warning', `⚠ ${taskId} cancelled`);
+        clearMs = NOTIFY_CLEAR_MS;
+    }
+    else {
+        line = theme.fg('error', `✘ ${taskId} failed${reason ? ': ' + reason : ''}`);
+        clearMs = FAIL_CLEAR_MS;
+    }
+    try {
+        ctx.ui.setWidget(WIDGET_KEY, [line]);
+    }
+    catch {
+        /* stale ctx */
+    }
+    setTimeout(() => {
+        try {
+            ctx.ui.setWidget(WIDGET_KEY, undefined);
+        }
+        catch {
+            /* stale ctx */
+        }
+    }, clearMs);
+}

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

@@ -0,0 +1,17 @@
+export interface BraveResult {
+    title: string;
+    url: string;
+    description: string;
+}
+export interface BraveSearchOpts {
+    apiKey: string;
+    count?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export declare class BraveSearchError extends Error {
+    readonly kind: 'auth' | 'rate-limit' | 'http' | 'network' | 'aborted';
+    readonly status?: number | undefined;
+    constructor(message: string, kind: 'auth' | 'rate-limit' | 'http' | 'network' | 'aborted', status?: number | undefined);
+}
+export declare function braveSearch(query: string, opts: BraveSearchOpts): Promise<BraveResult[]>;

package/dist/workers/brave-search.js

@@ -0,0 +1,77 @@
+const BRAVE_ENDPOINT = 'https://api.search.brave.com/res/v1/web/search';
+const DEFAULT_COUNT = 10;
+const MAX_COUNT = 20;
+const DEFAULT_TIMEOUT_MS = 10_000;
+export class BraveSearchError extends Error {
+    kind;
+    status;
+    constructor(message, kind, status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.name = 'BraveSearchError';
+    }
+}
+export async function braveSearch(query, opts) {
+    const count = Math.max(1, Math.min(MAX_COUNT, opts.count ?? DEFAULT_COUNT));
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const url = `${BRAVE_ENDPOINT}?q=${encodeURIComponent(query)}&count=${count}`;
+    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 });
+    }
+    try {
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    accept: 'application/json',
+                    'x-subscription-token': opts.apiKey
+                },
+                signal: internalController.signal
+            });
+        }
+        catch (err) {
+            if (userAborted) {
+                throw new BraveSearchError('Search aborted.', 'aborted');
+            }
+            throw new BraveSearchError(`Brave Search request failed: ${describeError(err)}`, 'network');
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new BraveSearchError(`Brave Search rejected the key (HTTP ${response.status}). Check BRAVE_SEARCH_API_KEY.`, 'auth', response.status);
+        }
+        if (response.status === 429) {
+            throw new BraveSearchError('Brave Search rate limit hit (HTTP 429). Try again in a moment.', 'rate-limit', 429);
+        }
+        if (!response.ok) {
+            throw new BraveSearchError(`Brave Search HTTP ${response.status} ${response.statusText}`, 'http', response.status);
+        }
+        const body = (await response.json());
+        const rawResults = body.web?.results ?? [];
+        return rawResults
+            .filter((r) => typeof r.title === 'string'
+            && typeof r.url === 'string'
+            && typeof r.description === 'string')
+            .map(r => ({ title: r.title, url: r.url, description: r.description }));
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+        if (opts.signal)
+            opts.signal.removeEventListener('abort', onUserAbort);
+    }
+}
+function describeError(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}

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

@@ -0,0 +1,16 @@
+export interface SyncStatement {
+    get(...args: unknown[]): unknown;
+    all(...args: unknown[]): unknown[];
+    run(...args: unknown[]): unknown;
+}
+export interface SyncDb {
+    exec(sql: string): void;
+    prepare(sql: string): SyncStatement;
+    close(): void;
+}
+export interface CacheHandle {
+    db: SyncDb;
+    close(): void;
+}
+export declare function defaultCachePath(): string;
+export declare function openCache(dbPath?: string): CacheHandle;

package/dist/workers/docs-cache.js

@@ -0,0 +1,66 @@
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS packages (
+  name         TEXT NOT NULL,
+  version      TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  indexed_at   INTEGER NOT NULL,
+  PRIMARY KEY (name, version)
+);
+
+CREATE TABLE IF NOT EXISTS chunks (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  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 VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
+  content,
+  content='chunks',
+  content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
+  INSERT INTO chunks_fts(rowid, content) VALUES (new.id, new.content);
+END;
+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;
+`;
+const req = createRequire(import.meta.url);
+function openDb(dbPath) {
+    if (typeof globalThis.Bun !== 'undefined') {
+        // Bun runtime: use bun:sqlite
+        const { Database } = req('bun:sqlite');
+        return new Database(dbPath);
+    }
+    // Node.js runtime: use node:sqlite
+    const { DatabaseSync } = req('node:sqlite');
+    return new DatabaseSync(dbPath);
+}
+export function defaultCachePath() {
+    const base = process.env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), '.cache');
+    return path.join(base, 'pi-worker', 'docs.sqlite');
+}
+export function openCache(dbPath) {
+    const resolved = dbPath ?? defaultCachePath();
+    if (resolved !== ':memory:') {
+        fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    }
+    const db = openDb(resolved);
+    db.exec('PRAGMA journal_mode = WAL;');
+    db.exec('PRAGMA synchronous = NORMAL;');
+    db.exec('PRAGMA foreign_keys = ON;');
+    db.exec(SCHEMA_SQL);
+    return {
+        db,
+        close: () => db.close()
+    };
+}

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

@@ -0,0 +1,86 @@
+import { openCache as defaultOpenCache } from './docs-cache.js';
+import { ensureIndexed as defaultEnsureIndexed } from './docs-index.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';
+import { type SpawnFn } from '../shared/child-process.js';
+export type DocsRawResult = {
+    kind: 'ok';
+    pkg: ResolvedPackage;
+    chunks: RetrievedChunk[];
+    hitCache: boolean;
+    indexingMs?: number;
+    indexedFiles?: number;
+    cacheError?: string;
+    autoInstalled?: boolean;
+    npmVersion?: NpmVersionInfo | null;
+} | {
+    kind: 'not_installed';
+    pkg: string;
+    npmVersion?: NpmVersionInfo | null;
+} | {
+    kind: 'no_chunks';
+    pkg: ResolvedPackage;
+    hitCache: boolean;
+    indexedFiles?: number;
+    cacheError?: string;
+    autoInstalled?: boolean;
+    npmVersion?: NpmVersionInfo | null;
+} | {
+    kind: 'error';
+    message: string;
+    resolveError?: 'not_installed' | 'invalid_name';
+    installError?: string;
+    version?: string;
+    hitCache?: boolean;
+    cacheError?: string;
+    autoInstalled?: boolean;
+    npmVersion?: NpmVersionInfo | null;
+};
+export interface DocsRawInput {
+    pkg: string;
+    query: string;
+    cwd: string;
+    autoInstall?: boolean;
+    resolvePackage?: typeof defaultResolvePackage;
+    ensureIndexed?: typeof defaultEnsureIndexed;
+    retrieveChunks?: typeof defaultRetrieveChunks;
+    openCache?: typeof defaultOpenCache;
+    spawn?: SpawnFn;
+    npmVersionLookup?: typeof defaultNpmVersionLookup;
+    signal?: AbortSignal;
+}
+export interface DocsFocusedResult {
+    answer: string;
+    excerpt?: string;
+    excerptVerified?: boolean;
+    pkg: ResolvedPackage;
+    version: string;
+    exitCode: number;
+    aborted: boolean;
+    stderr: string;
+    hitCache?: boolean;
+    indexingMs?: number;
+    indexedFiles?: number;
+    chunksRetrieved?: number;
+    cacheError?: string;
+    autoInstalled?: boolean;
+    npmVersion?: NpmVersionInfo | null;
+}
+export type DocsFocusedInput = DocsRawInput;
+export declare function extractParentPackage(moduleName: string): string;
+export declare function getDocsModulesDir(): string;
+export declare function ensureDocsModulesDir(dir: string): void;
+export declare function runAutoInstall(spawn: SpawnFn, packageName: string, signal: AbortSignal | undefined): Promise<{
+    success: boolean;
+    installDir: string;
+    stderr: string;
+}>;
+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;
+/** Thin wrapper so existing callers using the pkg-based signature still work. */
+export declare function formatResultText(pkg: ResolvedPackage, parsed: {
+    answer: string;
+    excerpt?: string;
+}, verified: boolean | undefined): string;