@taurgis/bonsai 1.0.0

package/dist/lib/research/revalidate.js

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto';
+import { getSiteModuleById } from '../../sites/index.js';
+import { fetchStaticHtml } from './fetcher.js';
+import { extractHtmlContent } from './extract.js';
+import { writeArtifact } from './storage.js';
+import { evaluateFreshness, getPolicy } from './freshness.js';
+import { compressMarkdown } from './compress.js';
+import { estimateTokens } from './token-estimate.js';
+import { fetchRenderedHtml } from './browser.js';
+function buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime, compressed) {
+    const contentHash = createHash('sha256').update(extraction.detailedMarkdown).digest('hex');
+    const staleAfterTime = new Date(currentTime);
+    const { freshWindowMs } = getPolicy(tier, ttl);
+    staleAfterTime.setTime(staleAfterTime.getTime() + freshWindowMs);
+    return {
+        schema_version: 1,
+        artifact_type: 'source',
+        source_url: url,
+        source_urls: [url],
+        normalized_url: normalizedUrl,
+        cache_key: cacheKey,
+        topic: null,
+        tags: [],
+        format_available: ['compressed', 'detailed'],
+        tier,
+        ttl,
+        fetched_at: currentTime.toISOString(),
+        validated_at: currentTime.toISOString(),
+        stale_after: staleAfterTime.toISOString(),
+        capture_method: 'static_fetch',
+        extraction_status: 'extracted',
+        extraction_confidence: extraction.confidence,
+        quality_notes: extraction.qualityNotes,
+        supplied_at: null,
+        supplied_by: null,
+        etag: fetchResult.etag,
+        last_modified: fetchResult.lastModified,
+        content_hash: contentHash,
+        token_estimate: {
+            compressed: estimateTokens(compressed),
+            detailed: estimateTokens(extraction.detailedMarkdown),
+        },
+        status: 'active',
+        site_module_id: null,
+        docs_engine: null,
+        docs_framework: null,
+        source_doc_url: null,
+        search_provider: null,
+        parent_cache_key: null,
+        section_anchor: null,
+        section_heading_path: null,
+    };
+}
+/**
+ * Helper to construct a ResearchArtifact from a fresh HTML fetch.
+ */
+export function createArtifactFromFetch(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime) {
+    const compressed = compressMarkdown(extraction.detailedMarkdown);
+    const metadata = buildMetadata(url, normalizedUrl, cacheKey, fetchResult, extraction, tier, ttl, currentTime, compressed);
+    return {
+        metadata,
+        summary: extraction.title,
+        compressed,
+        detailed: extraction.detailedMarkdown,
+        provenance: `Fetched from ${url} on ${currentTime.toISOString()}`,
+    };
+}
+function preserveUserMetadata(source, target, rendered) {
+    target.metadata.topic = source.topic;
+    target.metadata.tags = [...source.tags];
+    target.metadata.site_module_id = source.site_module_id;
+    // Carry forward docs-engine capability provenance so revalidation doesn't drop it.
+    target.metadata.docs_engine = source.docs_engine;
+    target.metadata.docs_framework = source.docs_framework;
+    target.metadata.search_provider = source.search_provider;
+    target.metadata.source_doc_url = source.source_doc_url;
+    if (rendered)
+        target.metadata.capture_method = 'browser_fallback';
+}
+// Builds a refreshed artifact from a fresh fetch, carries over user metadata, persists it, and
+// returns the "refreshed" result. Shared by both refresh paths (conditional-request fallthrough
+// and site-module re-fetch), which differ only in how fetchResult/extraction are obtained.
+function persistRefreshedArtifact(dataDir, meta, fetchResult, extraction, currentTime, options) {
+    const refreshed = createArtifactFromFetch(meta.source_url, meta.normalized_url, meta.cache_key, fetchResult, extraction, meta.tier, options.ttlOverride || meta.ttl, currentTime);
+    preserveUserMetadata(meta, refreshed, options.rendered);
+    writeArtifact(dataDir, meta.cache_key, refreshed);
+    return { status: 'refreshed', artifact: refreshed };
+}
+async function handleRevalidateResponse(dataDir, existing, fetchResult, currentTime, options) {
+    const meta = existing.metadata;
+    if (fetchResult.status === 304) {
+        const updated = {
+            ...existing,
+            metadata: {
+                ...meta,
+                validated_at: currentTime.toISOString(),
+            },
+        };
+        const staleAfterTime = new Date(currentTime);
+        const { freshWindowMs } = getPolicy(meta.tier, options.ttlOverride || meta.ttl);
+        staleAfterTime.setTime(staleAfterTime.getTime() + freshWindowMs);
+        updated.metadata.stale_after = staleAfterTime.toISOString();
+        writeArtifact(dataDir, meta.cache_key, updated);
+        return { status: 'revalidated', artifact: updated };
+    }
+    const extraction = extractHtmlContent(fetchResult.content, fetchResult.finalUrl);
+    return persistRefreshedArtifact(dataDir, meta, fetchResult, extraction, currentTime, options);
+}
+/**
+ * Revalidates a stale cache artifact using conditional request headers,
+ * falling back to stale serving within the grace period if the remote host is offline.
+ */
+export async function revalidateCache(dataDir, existing, currentTime, options) {
+    const meta = existing.metadata;
+    const freshness = evaluateFreshness(meta, currentTime, options.ttlOverride);
+    if (freshness === 'fresh') {
+        return { status: 'revalidated', artifact: existing };
+    }
+    const revalHeaders = {};
+    if (meta.etag) {
+        revalHeaders['If-None-Match'] = meta.etag;
+    }
+    if (meta.last_modified) {
+        revalHeaders['If-Modified-Since'] = meta.last_modified;
+    }
+    try {
+        const siteModule = meta.site_module_id ? getSiteModuleById(meta.site_module_id) : null;
+        if (siteModule?.fetchPage) {
+            // Site modules use custom fetch strategies that don't speak HTTP conditional requests
+            // (no ETag/If-Modified-Since), so a full re-fetch is the only correct revalidation here.
+            const { fetchResult, extraction } = await siteModule.fetchPage(meta.source_url);
+            return persistRefreshedArtifact(dataDir, meta, fetchResult, extraction, currentTime, options);
+        }
+        const fetchResult = options.rendered
+            ? await fetchRenderedHtml(meta.source_url)
+            : await fetchStaticHtml(meta.source_url, {
+                headers: revalHeaders,
+            });
+        return await handleRevalidateResponse(dataDir, existing, fetchResult, currentTime, options);
+    }
+    catch (err) {
+        if (freshness === 'stale_grace') {
+            return {
+                status: 'stale',
+                artifact: existing,
+                allowed: options.allowStale,
+                error: `Revalidation failed: ${err.message}. Serving stale content within grace period.`,
+            };
+        }
+        throw new Error(`Revalidation failed and cache has expired beyond the grace period: ${err.message}`);
+    }
+}

package/dist/lib/research/schema.d.ts

@@ -0,0 +1,47 @@
+export interface TokenEstimate {
+    compressed: number | null;
+    detailed: number | null;
+}
+export type CaptureMethod = 'static_fetch' | 'browser_fallback' | 'agent_supplied' | 'route_markdown' | 'github_source';
+export interface ResearchArtifactMetadata {
+    schema_version: number;
+    artifact_type: 'source' | 'research_note' | 'index' | 'section';
+    source_url: string;
+    source_urls: string[];
+    normalized_url: string;
+    cache_key: string;
+    topic: string | null;
+    tags: string[];
+    format_available: string[];
+    tier: 'stable' | 'standard' | 'volatile';
+    ttl: string | null;
+    fetched_at: string | null;
+    validated_at: string | null;
+    stale_after: string | null;
+    capture_method: CaptureMethod | null;
+    extraction_status: 'extracted' | 'agent_supplied' | 'failed' | null;
+    extraction_confidence: 'high' | 'medium' | 'low' | null;
+    quality_notes: string[];
+    supplied_at: string | null;
+    supplied_by: string | null;
+    etag: string | null;
+    last_modified: string | null;
+    content_hash: string;
+    token_estimate: TokenEstimate;
+    status: 'active' | 'archived';
+    site_module_id: string | null;
+    docs_engine: string | null;
+    docs_framework: string | null;
+    source_doc_url: string | null;
+    search_provider: string | null;
+    parent_cache_key: string | null;
+    section_anchor: string | null;
+    section_heading_path: string | null;
+}
+export interface ResearchArtifact {
+    metadata: ResearchArtifactMetadata;
+    summary: string;
+    compressed: string;
+    detailed: string;
+    provenance: string;
+}

package/dist/lib/research/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/research/secret-scan.d.ts

@@ -0,0 +1,5 @@
+import type { ResearchArtifact } from './schema.js';
+/** Return the label of the first secret pattern found in `text`, or null if none match. */
+export declare function detectSecret(text: string): string | null;
+/** Scan every content field of an artifact. Returns the detected secret's label, or null. */
+export declare function scanArtifactForSecret(artifact: ResearchArtifact): string | null;

package/dist/lib/research/secret-scan.js

@@ -0,0 +1,37 @@
+const SECRET_PATTERNS = [
+    { label: 'AWS access key id', re: /\bAKIA[0-9A-Z]{16}\b/ },
+    { label: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/ },
+    { label: 'GitHub fine-grained PAT', re: /\bgithub_pat_[A-Za-z0-9_]{80,}\b/ },
+    { label: 'Slack token', re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/ },
+    { label: 'OpenAI/Anthropic-style API key', re: /\bsk-[A-Za-z0-9_-]{20,}\b/ },
+    { label: 'Google API key', re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    {
+        label: 'JSON Web Token',
+        re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/,
+    },
+    { label: 'Bearer token', re: /\bBearer\s+[A-Za-z0-9._~+/-]{20,}=*/ },
+    {
+        label: 'Private key block',
+        re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----/,
+    },
+    {
+        // Generic `api_key = "…"` / `secret: …` style assignments with a non-trivial value.
+        label: 'credential assignment',
+        re: /\b(?:api[_-]?key|secret|token|password|passwd|client[_-]?secret|access[_-]?token)\b\s*[:=]\s*['"]?[A-Za-z0-9._\-/+]{16,}/i,
+    },
+];
+/** Return the label of the first secret pattern found in `text`, or null if none match. */
+export function detectSecret(text) {
+    for (const { label, re } of SECRET_PATTERNS) {
+        if (re.test(text))
+            return label;
+    }
+    return null;
+}
+/** Scan every content field of an artifact. Returns the detected secret's label, or null. */
+export function scanArtifactForSecret(artifact) {
+    const haystack = [artifact.summary, artifact.compressed, artifact.detailed, artifact.provenance]
+        .filter(Boolean)
+        .join('\n');
+    return detectSecret(haystack);
+}

package/dist/lib/research/secure-write.d.ts

@@ -0,0 +1,16 @@
+import type { StoreRoots } from './store-roots.js';
+import type { ResearchArtifact } from './schema.js';
+export interface SecureWriteResult {
+    /** Data dir the artifact was actually written to. */
+    dataDir: string;
+    /** True when a project-bound write was redirected to global because of a detected secret. */
+    redirected: boolean;
+    /** Label of the detected secret type when redirected, otherwise null. Never the secret value. */
+    secretLabel: string | null;
+}
+/**
+ * Write an artifact to the configured write root, except when it contains a secret and the
+ * target is a (potentially committed) project cache — those are redirected to the global cache.
+ * Returns where it landed so the caller can warn the user and report the real path.
+ */
+export declare function writeArtifactSecurely(roots: StoreRoots, key: string, artifact: ResearchArtifact): SecureWriteResult;

package/dist/lib/research/secure-write.js

@@ -0,0 +1,17 @@
+import { writeArtifact } from './storage.js';
+import { scanArtifactForSecret } from './secret-scan.js';
+/**
+ * Write an artifact to the configured write root, except when it contains a secret and the
+ * target is a (potentially committed) project cache — those are redirected to the global cache.
+ * Returns where it landed so the caller can warn the user and report the real path.
+ */
+export function writeArtifactSecurely(roots, key, artifact) {
+    const isProjectWrite = roots.writeRoot !== roots.globalRoot;
+    const secretLabel = isProjectWrite ? scanArtifactForSecret(artifact) : null;
+    if (secretLabel) {
+        writeArtifact(roots.globalRoot, key, artifact);
+        return { dataDir: roots.globalRoot, redirected: true, secretLabel };
+    }
+    writeArtifact(roots.writeRoot, key, artifact);
+    return { dataDir: roots.writeRoot, redirected: false, secretLabel: null };
+}

package/dist/lib/research/storage.d.ts

@@ -0,0 +1,52 @@
+import type { ResearchArtifact } from './schema.js';
+/**
+ * Scans a cache directory and maps each valid artifact file through a callback.
+ * Return null from the callback to skip an entry; all non-null results are collected.
+ * Parse/read errors are swallowed silently, matching the convention in the command layer.
+ */
+export declare function scanCacheDir<T>(dir: string, fn: (artifact: ResearchArtifact, filePath: string) => T | null): T[];
+/**
+ * Returns the absolute file path for a cache key within the data directory.
+ * Ensures that the key is simple hex to prevent directory traversal.
+ */
+export declare function getArtifactPath(dataDir: string, key: string): string;
+/**
+ * Scans the research storage directory, reading metadata of all valid markdown files
+ * to find the active artifact for the given cache key with the newest validated_at timestamp.
+ * If a corrupt artifact is found, it is skipped and archived as corrupt.
+ */
+export declare function findArtifact(dataDir: string, key: string): ResearchArtifact | null;
+/**
+ * Checks if a cached artifact exists on disk for a given cache key.
+ */
+export declare function hasArtifact(dataDir: string, key: string): boolean;
+/**
+ * Writes a ResearchArtifact to disk, creating the research storage folder if needed.
+ * Writes to a temporary file first, then atomically renames it.
+ * Archives the previous artifact if it exists.
+ */
+export declare function writeArtifact(dataDir: string, key: string, artifact: ResearchArtifact): void;
+/**
+ * Reads and parses a ResearchArtifact from disk using the scan-based lookup.
+ */
+export declare function readArtifact(dataDir: string, key: string): ResearchArtifact;
+export interface LocatedArtifact {
+    artifact: ResearchArtifact;
+    /** The data dir the artifact was found in (project or global). */
+    dataDir: string;
+    /** The artifact's actual file path within that data dir. */
+    path: string;
+}
+/**
+ * Looks up a cache key across an ordered list of data dirs (project first, then global),
+ * returning the first match along with where it lives. Implements the project→global
+ * read fallback: a missing project entry still resolves against the global cache.
+ */
+export declare function locateArtifact(dataDirs: string[], key: string): LocatedArtifact | null;
+/**
+ * Multi-root variant of {@link scanCacheDir}. Scans the `research/` dir of each data dir in
+ * order and deduplicates by cache key so an entry present in an earlier root (project) shadows
+ * the same key in a later root (global) — even when the callback filters it out. Composes
+ * scanCacheDir so the file-format and read/parse rules stay defined in exactly one place.
+ */
+export declare function scanCacheDirs<T>(dataDirs: string[], fn: (artifact: ResearchArtifact, filePath: string) => T | null): T[];

package/dist/lib/research/storage.js

@@ -0,0 +1,182 @@
+import { join } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync, renameSync, } from 'node:fs';
+import { parseArtifact, serializeArtifact } from './artifact.js';
+function isResearchFile(file) {
+    return (file.endsWith('.md') &&
+        !file.includes('.tmp') &&
+        !file.includes('.corrupt') &&
+        !file.includes('.superseded'));
+}
+/**
+ * Scans a cache directory and maps each valid artifact file through a callback.
+ * Return null from the callback to skip an entry; all non-null results are collected.
+ * Parse/read errors are swallowed silently, matching the convention in the command layer.
+ */
+export function scanCacheDir(dir, fn) {
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    for (const file of readdirSync(dir)) {
+        if (!isResearchFile(file))
+            continue;
+        try {
+            const content = readFileSync(join(dir, file), 'utf-8');
+            const result = fn(parseArtifact(content), join(dir, file));
+            if (result !== null)
+                results.push(result);
+        }
+        catch { }
+    }
+    return results;
+}
+/**
+ * Returns the absolute file path for a cache key within the data directory.
+ * Ensures that the key is simple hex to prevent directory traversal.
+ */
+export function getArtifactPath(dataDir, key) {
+    if (!/^[a-f0-9]+$/.test(key)) {
+        throw new Error(`Invalid cache key "${key}". Keys must be alphanumeric hex strings.`);
+    }
+    return join(dataDir, 'research', `${key}.md`);
+}
+function processFileForLookup(file, dir, key) {
+    if (!file.endsWith('.md') || file.includes('.tmp')) {
+        return null;
+    }
+    const filePath = join(dir, file);
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const artifact = parseArtifact(content);
+        if (artifact.metadata.cache_key === key && artifact.metadata.status === 'active') {
+            return artifact;
+        }
+    }
+    catch (err) {
+        console.warn(`Warning: Corrupt research artifact found at "${filePath}": ${err.message}`);
+        try {
+            const corruptPath = `${filePath}.corrupt.${Date.now()}`;
+            renameSync(filePath, corruptPath);
+            console.warn(`Archived corrupt artifact to "${corruptPath}"`);
+        }
+        catch (archiveErr) {
+            console.error(`Failed to archive corrupt artifact: ${archiveErr.message}`);
+        }
+    }
+    return null;
+}
+/**
+ * Scans the research storage directory, reading metadata of all valid markdown files
+ * to find the active artifact for the given cache key with the newest validated_at timestamp.
+ * If a corrupt artifact is found, it is skipped and archived as corrupt.
+ */
+export function findArtifact(dataDir, key) {
+    const dir = join(dataDir, 'research');
+    if (!existsSync(dir)) {
+        return null;
+    }
+    let bestArtifact = null;
+    let bestValidatedAt = -1;
+    const files = readdirSync(dir);
+    for (const file of files) {
+        const artifact = processFileForLookup(file, dir, key);
+        if (!artifact) {
+            continue;
+        }
+        const validatedAt = artifact.metadata.validated_at
+            ? new Date(artifact.metadata.validated_at).getTime()
+            : 0;
+        if (validatedAt > bestValidatedAt) {
+            bestArtifact = artifact;
+            bestValidatedAt = validatedAt;
+        }
+    }
+    return bestArtifact;
+}
+/**
+ * Checks if a cached artifact exists on disk for a given cache key.
+ */
+export function hasArtifact(dataDir, key) {
+    try {
+        return findArtifact(dataDir, key) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Writes a ResearchArtifact to disk, creating the research storage folder if needed.
+ * Writes to a temporary file first, then atomically renames it.
+ * Archives the previous artifact if it exists.
+ */
+export function writeArtifact(dataDir, key, artifact) {
+    const path = getArtifactPath(dataDir, key);
+    const dir = join(dataDir, 'research');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const tmpPath = `${path}.${Date.now()}.${Math.random().toString(36).substring(2, 7)}.tmp`;
+    const content = serializeArtifact(artifact);
+    writeFileSync(tmpPath, content, 'utf-8');
+    try {
+        if (existsSync(path)) {
+            try {
+                const existingContent = readFileSync(path, 'utf-8');
+                const archivePath = join(dir, `${key}.superseded.${Date.now()}.md`);
+                writeFileSync(archivePath, existingContent, 'utf-8');
+            }
+            catch (err) {
+                console.warn(`Warning: failed to archive superseded artifact: ${err.message}`);
+            }
+        }
+        renameSync(tmpPath, path);
+    }
+    catch (err) {
+        if (existsSync(tmpPath)) {
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch { }
+        }
+        throw err;
+    }
+}
+/**
+ * Reads and parses a ResearchArtifact from disk using the scan-based lookup.
+ */
+export function readArtifact(dataDir, key) {
+    const artifact = findArtifact(dataDir, key);
+    if (!artifact) {
+        throw new Error(`Artifact not found for key: ${key}`);
+    }
+    return artifact;
+}
+/**
+ * Looks up a cache key across an ordered list of data dirs (project first, then global),
+ * returning the first match along with where it lives. Implements the project→global
+ * read fallback: a missing project entry still resolves against the global cache.
+ */
+export function locateArtifact(dataDirs, key) {
+    for (const dataDir of dataDirs) {
+        const artifact = findArtifact(dataDir, key);
+        if (artifact) {
+            return { artifact, dataDir, path: getArtifactPath(dataDir, key) };
+        }
+    }
+    return null;
+}
+/**
+ * Multi-root variant of {@link scanCacheDir}. Scans the `research/` dir of each data dir in
+ * order and deduplicates by cache key so an entry present in an earlier root (project) shadows
+ * the same key in a later root (global) — even when the callback filters it out. Composes
+ * scanCacheDir so the file-format and read/parse rules stay defined in exactly one place.
+ */
+export function scanCacheDirs(dataDirs, fn) {
+    const seen = new Set();
+    return dataDirs.flatMap((dataDir) => scanCacheDir(join(dataDir, 'research'), (artifact, filePath) => {
+        const key = artifact.metadata.cache_key;
+        if (seen.has(key))
+            return null;
+        seen.add(key);
+        return fn(artifact, filePath);
+    }));
+}

package/dist/lib/research/store-roots.d.ts

@@ -0,0 +1,29 @@
+import type { StorageMode } from '../config/schema.js';
+/**
+ * Project-level cache directory name, placed at the current working directory.
+ * Storage helpers append `research/` to a data dir, so the on-disk cache for a
+ * project lives at `<cwd>/.bonsai/research/`.
+ */
+export declare const PROJECT_CACHE_DIRNAME = ".bonsai";
+export declare function projectDataDir(cwd: string): string;
+export interface StoreRoots {
+    mode: StorageMode;
+    /** Data dir new artifacts are written to (before secret routing). */
+    writeRoot: string;
+    /** Global data dir — the safe destination for secret-bearing artifacts. */
+    globalRoot: string;
+    /** Data dirs to read from, in lookup order. Project first, then global fallback. */
+    readRoots: string[];
+}
+/**
+ * Map a resolved storage mode onto concrete data dirs. In project mode, reads fall
+ * back to the global cache so a missing project entry still resolves against global.
+ */
+export declare function resolveStoreRoots(mode: StorageMode, oclifDataDir: string, cwd: string): StoreRoots;
+/** Load config (file + env + optional flag) and resolve the concrete store roots. */
+export declare function loadStoreRoots(opts: {
+    configDir: string | undefined;
+    cwd: string;
+    dataDir: string;
+    flagOverride?: StorageMode;
+}): StoreRoots;

package/dist/lib/research/store-roots.js

@@ -0,0 +1,28 @@
+import { join } from 'node:path';
+import { loadStorageMode } from '../config/index.js';
+/**
+ * Project-level cache directory name, placed at the current working directory.
+ * Storage helpers append `research/` to a data dir, so the on-disk cache for a
+ * project lives at `<cwd>/.bonsai/research/`.
+ */
+export const PROJECT_CACHE_DIRNAME = '.bonsai';
+export function projectDataDir(cwd) {
+    return join(cwd, PROJECT_CACHE_DIRNAME);
+}
+/**
+ * Map a resolved storage mode onto concrete data dirs. In project mode, reads fall
+ * back to the global cache so a missing project entry still resolves against global.
+ */
+export function resolveStoreRoots(mode, oclifDataDir, cwd) {
+    const globalRoot = oclifDataDir;
+    if (mode === 'project') {
+        const project = projectDataDir(cwd);
+        return { mode, writeRoot: project, globalRoot, readRoots: [project, globalRoot] };
+    }
+    return { mode, writeRoot: globalRoot, globalRoot, readRoots: [globalRoot] };
+}
+/** Load config (file + env + optional flag) and resolve the concrete store roots. */
+export function loadStoreRoots(opts) {
+    const mode = loadStorageMode(opts.configDir, opts.cwd, opts.flagOverride);
+    return resolveStoreRoots(mode, opts.dataDir, opts.cwd);
+}

package/dist/lib/research/token-estimate.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Estimates the token count of a given text string.
+ * Uses the simple rule-of-thumb formula: ceil(character_count / 4).
+ */
+export declare function estimateTokens(text: string): number;

package/dist/lib/research/token-estimate.js

@@ -0,0 +1,7 @@
+/**
+ * Estimates the token count of a given text string.
+ * Uses the simple rule-of-thumb formula: ceil(character_count / 4).
+ */
+export function estimateTokens(text) {
+    return Math.ceil((text || '').length / 4);
+}

package/dist/lib/research/url.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Checks if a literal IPv4 address is in a safe range.
+ * Rejects loopback, private RFC1918, and link-local ranges.
+ */
+export declare function isSafeIpv4(ip: string): boolean;
+/**
+ * Checks if a literal IPv6 address is in a safe range.
+ * Rejects loopback, unspecified, link-local, and mapped unsafe IPv4 ranges.
+ */
+export declare function isSafeIpv6(ip: string): boolean;
+/**
+ * Checks if a literal IP address is a safe public IP.
+ * Returns false for loopback, private, link-local, or unspecified ranges.
+ */
+export declare function isSafeIp(ip: string): boolean;
+/**
+ * Validates a hostname to ensure it is not blocked (e.g. localhost or literal private IP).
+ */
+export declare function validateHostname(hostname: string): void;
+/**
+ * Parses and normalizes a URL. Strips fragments, credentials, default ports,
+ * and sorts query parameters lexicographically.
+ */
+export declare function normalizeUrl(input: string): string;