devharness 0.8.0

package/build/formatters/console-formatter.js

@@ -0,0 +1,338 @@
+/**
+ * Console Message Formatting
+ *
+ * Formats console messages for different output modes:
+ * - Preview: Compact CSV for list/recent/search (minimal tokens)
+ * - Summary: Smart truncation for detail view (budget-constrained)
+ * - Full: Complete message with all data
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+/** Token budget for smart summary mode */
+export const DEFAULT_SUMMARY_TOKEN_BUDGET = 100;
+/** Max characters for preview text in list mode */
+const DEFAULT_PREVIEW_MAX_CHARS = 200;
+/** Budget allocation for summary mode */
+const SUMMARY_BUDGET = {
+    text: 0.6, // 60% for message text
+    args: 0.25, // 25% for arguments
+    stack: 0.15, // 15% for stack trace
+};
+// =============================================================================
+// Token Estimation
+// =============================================================================
+/**
+ * Estimate token count for a value (~4 chars per token)
+ */
+export function estimateTokens(value) {
+    const str = typeof value === 'string' ? value : JSON.stringify(value);
+    return Math.ceil(str.length / 4);
+}
+// =============================================================================
+// Preview Mode (for list/recent/search)
+// =============================================================================
+/**
+ * Create a compact preview of a console message for list views.
+ * Returns minimal data with token count for the full message.
+ */
+export function createMessagePreview(message) {
+    const fullTokens = estimateTokens({ text: message.text, args: message.args });
+    let preview = message.text;
+    let truncated = false;
+    if (preview.length > DEFAULT_PREVIEW_MAX_CHARS) {
+        preview = preview.substring(0, DEFAULT_PREVIEW_MAX_CHARS) + '...';
+        truncated = true;
+    }
+    // Mark as truncated if args contain significant content
+    if (message.args && message.args.length > 0 && estimateTokens(message.args) > 10) {
+        truncated = true;
+    }
+    return { id: message.id, type: message.type, preview, tokens: fullTokens, truncated };
+}
+/**
+ * Format message previews as CSV and calculate stats
+ */
+export function formatPreviewsWithStats(previews) {
+    const header = 'id,type,tokens,truncated,preview';
+    const rows = previews.map(p => `${p.id},${p.type},${p.tokens},${p.truncated},${escapeCsvValue(p.preview)}`);
+    return {
+        csv: [header, ...rows].join('\n'),
+        truncatedCount: previews.filter(p => p.truncated).length,
+        totalTokens: previews.reduce((sum, p) => sum + p.tokens, 0),
+    };
+}
+/**
+ * Build complete list response text
+ */
+export function buildListResponseText(headerText, csv, truncatedCount, totalTokens) {
+    return `${headerText}\nTruncated: ${truncatedCount}, Total tokens if expanded: ~${totalTokens}\n\n\`\`\`csv\n${csv}\n\`\`\`\n\nUse \`console({ action: 'get', id: '...' })\` to expand a message.`;
+}
+// =============================================================================
+// Summary Mode (for detail view with budget)
+// =============================================================================
+/**
+ * Create a smart summary of a console message within a token budget.
+ * Prioritizes: text > args > stack trace
+ */
+export function createMessageSummary(message, tokenBudget = DEFAULT_SUMMARY_TOKEN_BUDGET) {
+    const fullTokens = estimateTokens({
+        text: message.text,
+        args: message.args,
+        stackTrace: message.stackTrace,
+    });
+    // If under budget, return as-is
+    if (fullTokens <= tokenBudget) {
+        return {
+            id: message.id,
+            type: message.type,
+            text: message.text,
+            args: message.args,
+            location: message.location,
+            stackTrace: message.stackTrace
+                ? { shown: message.stackTrace.length, total: message.stackTrace.length, frames: message.stackTrace }
+                : undefined,
+            timestamp: message.timestamp,
+            _tokens: { full: fullTokens, returned: fullTokens },
+        };
+    }
+    // Allocate budget
+    const textBudget = Math.floor(tokenBudget * SUMMARY_BUDGET.text);
+    const argsBudget = Math.floor(tokenBudget * SUMMARY_BUDGET.args);
+    const stackBudget = Math.floor(tokenBudget * SUMMARY_BUDGET.stack);
+    const result = {
+        id: message.id,
+        type: message.type,
+        text: message.text,
+        location: message.location,
+        timestamp: message.timestamp,
+        _tokens: { full: fullTokens, returned: 0 },
+    };
+    // Truncate text if needed
+    if (estimateTokens(message.text) > textBudget) {
+        const maxChars = textBudget * 4;
+        result.text = message.text.substring(0, maxChars) + '...';
+        result.textTruncated = { shown: maxChars, total: message.text.length };
+    }
+    // Summarize or include args
+    if (message.args && message.args.length > 0) {
+        if (estimateTokens(message.args) > argsBudget) {
+            result.argsSummary = summarizeArgs(message.args);
+        }
+        else {
+            result.args = message.args;
+        }
+    }
+    // Limit stack trace
+    if (message.stackTrace && message.stackTrace.length > 0) {
+        const maxFrames = Math.max(2, Math.floor(stackBudget / 10));
+        result.stackTrace = {
+            shown: Math.min(maxFrames, message.stackTrace.length),
+            total: message.stackTrace.length,
+            frames: message.stackTrace.slice(0, maxFrames),
+        };
+    }
+    result._tokens.returned = estimateTokens(result);
+    return result;
+}
+/**
+ * Generate hints for how to extract more data from a truncated summary
+ */
+export function generateSummaryHints(summary) {
+    const hints = [];
+    if (summary.textTruncated) {
+        hints.push(`Text truncated: ${summary.textTruncated.shown}/${summary.textTruncated.total} chars. Use \`textOffset\`/\`textLimit\` to extract more.`);
+    }
+    if (summary.argsSummary) {
+        hints.push(`Args summarized. Use \`argsIndex: N\` to get specific arg.`);
+    }
+    if (summary.stackTrace && summary.stackTrace.shown < summary.stackTrace.total) {
+        hints.push(`Stack trace: ${summary.stackTrace.shown}/${summary.stackTrace.total} frames shown. Use \`full: true\` for all.`);
+    }
+    return hints.length > 0 ? '\n' + hints.join('\n') : '';
+}
+/**
+ * Build summary response text
+ */
+export function buildSummaryResponseText(message, summary, jsonBlock) {
+    const hints = generateSummaryHints(summary);
+    return `Console message [${message.id}] - Type: ${message.type}\nTokens: ${summary._tokens.returned} returned / ${summary._tokens.full} full${hints}\n\n${jsonBlock}`;
+}
+/**
+ * Extract a portion of text from a message
+ */
+export function extractTextPortion(text, offset, limit) {
+    if (offset === undefined && limit === undefined) {
+        return { text };
+    }
+    const actualOffset = offset ?? 0;
+    const total = text.length;
+    if (limit !== undefined) {
+        return {
+            text: text.substring(actualOffset, actualOffset + limit),
+            extraction: { offset: actualOffset, limit, total, hasMore: actualOffset + limit < total },
+        };
+    }
+    if (actualOffset > 0) {
+        return {
+            text: text.substring(actualOffset),
+            extraction: { offset: actualOffset, total, hasMore: false },
+        };
+    }
+    return { text };
+}
+/**
+ * Extract a specific argument by index
+ */
+export function extractArgByIndex(args, index) {
+    if (!args || args.length === 0) {
+        return { error: 'Message has no args' };
+    }
+    if (index < 0 || index >= args.length) {
+        return { error: `argsIndex ${index} is out of range (0-${args.length - 1})` };
+    }
+    return { args: [args[index]], extraction: { index, total: args.length } };
+}
+// =============================================================================
+// TOON Formatting (for get action)
+// =============================================================================
+/**
+ * Format a value for TOON output
+ * - Wrap in () if contains spaces or special chars
+ * - Arrays use [item|item]
+ * - Objects use {key:value;...}
+ */
+function formatToonValue(value, maxDepth = 2, currentDepth = 0) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'string') {
+        // Escape special chars and wrap if needed
+        if (value.includes(';') || value.includes(':') || value.includes('|') ||
+            value.includes('{') || value.includes('}') || value.includes('[') ||
+            value.includes(']') || value.includes('(') || value.includes(')') ||
+            value.includes(' ') || value.includes('\n')) {
+            // Replace problematic chars and wrap
+            const escaped = value.replace(/[()]/g, '').replace(/\n/g, '\\n').substring(0, 200);
+            return `(${escaped}${value.length > 200 ? '...' : ''})`;
+        }
+        return value.substring(0, 100) + (value.length > 100 ? '...' : '');
+    }
+    if (currentDepth >= maxDepth) {
+        if (Array.isArray(value))
+            return `[Array:${value.length}]`;
+        return `[Object:${Object.keys(value).length}keys]`;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        const items = value.slice(0, 5).map(v => formatToonValue(v, maxDepth, currentDepth + 1));
+        const suffix = value.length > 5 ? `|+${value.length - 5}more` : '';
+        return `[${items.join('|')}${suffix}]`;
+    }
+    if (typeof value === 'object') {
+        const keys = Object.keys(value);
+        if (keys.length === 0)
+            return '{}';
+        const pairs = keys.slice(0, 5).map(k => `${k}:${formatToonValue(value[k], maxDepth, currentDepth + 1)}`);
+        const suffix = keys.length > 5 ? `;+${keys.length - 5}more` : '';
+        return `{${pairs.join(';')}${suffix}}`;
+    }
+    return String(value);
+}
+/**
+ * Format console message summary as TOON (one property per line for readability)
+ */
+export function formatSummaryAsToon(summary) {
+    const lines = [
+        `id:${summary.id}`,
+        `type:${summary.type}`,
+        `text:${formatToonValue(summary.text)}`,
+    ];
+    if (summary.textTruncated) {
+        lines.push(`textTruncated:{shown:${summary.textTruncated.shown};total:${summary.textTruncated.total}}`);
+    }
+    if (summary.argsSummary) {
+        lines.push(`argsSummary:(${summary.argsSummary})`);
+    }
+    else if (summary.args && summary.args.length > 0) {
+        lines.push(`args:${formatToonValue(summary.args)}`);
+    }
+    if (summary.location) {
+        const loc = summary.location;
+        lines.push(`location:{url:${formatToonValue(loc.url)};line:${loc.lineNumber};col:${loc.columnNumber}}`);
+    }
+    if (summary.stackTrace) {
+        const st = summary.stackTrace;
+        const frames = st.frames.map(f => `{url:${formatToonValue(f.url)};line:${f.lineNumber}}`).join('|');
+        lines.push(`stack:{shown:${st.shown};total:${st.total};frames:[${frames}]}`);
+    }
+    lines.push(`tokens:{full:${summary._tokens.full};returned:${summary._tokens.returned}}`);
+    return lines.join('\n');
+}
+/**
+ * Format full message detail as TOON (one property per line for readability)
+ */
+export function formatMessageDetailAsToon(data) {
+    const lines = [
+        `id:${data.id}`,
+        `type:${data.type}`,
+        `text:${formatToonValue(data.text)}`,
+    ];
+    if (data.args && data.args.length > 0) {
+        lines.push(`args:${formatToonValue(data.args)}`);
+    }
+    if (data.location) {
+        lines.push(`location:{url:${formatToonValue(data.location.url)};line:${data.location.lineNumber}}`);
+    }
+    if (data.stackTrace && data.stackTrace.length > 0) {
+        const frames = data.stackTrace.slice(0, 3).map(f => `{url:${formatToonValue(f.url)};line:${f.lineNumber}}`).join('|');
+        const suffix = data.stackTrace.length > 3 ? `|+${data.stackTrace.length - 3}more` : '';
+        lines.push(`stack:[${frames}${suffix}]`);
+    }
+    lines.push(`tokens:{full:${data._tokens.full};returned:${data._tokens.returned}}`);
+    if (data._textExtraction) {
+        const te = data._textExtraction;
+        lines.push(`textExtract:{offset:${te.offset};total:${te.total};hasMore:${te.hasMore}}`);
+    }
+    if (data._argsExtraction) {
+        lines.push(`argsExtract:{index:${data._argsExtraction.index};total:${data._argsExtraction.total}}`);
+    }
+    return lines.join('\n');
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function escapeCsvValue(value) {
+    if (value.includes(',') || value.includes('"') || value.includes('\n') || value.includes('\r')) {
+        return '"' + value.replace(/"/g, '""') + '"';
+    }
+    return value;
+}
+function summarizeArgs(args) {
+    return args.map((arg, i) => {
+        if (arg === null)
+            return `[${i}]: null`;
+        if (arg === undefined)
+            return `[${i}]: undefined`;
+        if (typeof arg === 'string')
+            return `[${i}]: string(${arg.length} chars)`;
+        if (typeof arg === 'number')
+            return `[${i}]: ${arg}`;
+        if (typeof arg === 'boolean')
+            return `[${i}]: ${arg}`;
+        if (Array.isArray(arg))
+            return `[${i}]: Array(${arg.length})`;
+        if (typeof arg === 'object') {
+            const keys = Object.keys(arg);
+            return `[${i}]: Object{${keys.slice(0, 3).join(', ')}${keys.length > 3 ? '...' : ''}}`;
+        }
+        return `[${i}]: ${typeof arg}`;
+    }).join(', ');
+}
+//# sourceMappingURL=console-formatter.js.map

package/build/formatters/console-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-formatter.js","sourceRoot":"","sources":["../../src/formatters/console-formatter.ts"],"names":[],"mappings":"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"}

package/build/helpers/parser-plugins.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Page-parser plugin loader.
+ *
+ * A parser plugin is a small ES module dropped into `.cdp-tools/parsers/`
+ * (project first, then `~/.cdp-tools/parsers/`). It is imported dynamically at
+ * call time — so adding or editing a parser needs no rebuild/restart of the
+ * server. Each plugin default-exports:
+ *
+ *   export default {
+ *     name: 'ai-overview',
+ *     description: 'Google AI Overview summary + cited links',
+ *     match: /google\.[a-z.]+\/search/,   // optional: hints it fits the URL
+ *     waitFor: () => boolean,             // optional: runs IN the page; the tool
+ *                                         //   waits for this to become true
+ *     extract: () => any,                 // required: runs IN the page (via
+ *                                         //   page.evaluate) and returns JSON
+ *   };
+ *
+ * IMPORTANT: `waitFor` and `extract` are serialized and executed in the browser
+ * context, so they must be self-contained — no closures over Node-side scope,
+ * no imports. Define any helpers inside the function body.
+ */
+export interface ParserPlugin {
+    name: string;
+    description?: string;
+    match?: RegExp;
+    /** Runs in the page; the tool waits until it returns true (or waitMs elapses). */
+    waitFor?: () => boolean;
+    /** Runs in the page via page.evaluate; returns JSON-serializable data. */
+    extract: () => unknown;
+}
+export interface ParserInfo {
+    name: string;
+    description?: string;
+    file: string;
+    /** true/false when the plugin declares a `match` and a URL was provided. */
+    matches?: boolean;
+}
+export declare function parserSearchPaths(): string[];
+/** List available plugins (project overrides global on name collision). */
+export declare function listParsers(url?: string): Promise<ParserInfo[]>;
+/** Load a single plugin by name. Throws if not found. */
+export declare function loadParser(name: string): Promise<ParserPlugin>;
+//# sourceMappingURL=parser-plugins.d.ts.map

package/build/helpers/parser-plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser-plugins.d.ts","sourceRoot":"","sources":["../../src/helpers/parser-plugins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACxB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAiBD,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAK5C;AAqBD,2EAA2E;AAC3E,wBAAsB,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAoBrE;AAED,yDAAyD;AACzD,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAWpE"}

package/build/helpers/parser-plugins.js

@@ -0,0 +1,102 @@
+/**
+ * Page-parser plugin loader.
+ *
+ * A parser plugin is a small ES module dropped into `.cdp-tools/parsers/`
+ * (project first, then `~/.cdp-tools/parsers/`). It is imported dynamically at
+ * call time — so adding or editing a parser needs no rebuild/restart of the
+ * server. Each plugin default-exports:
+ *
+ *   export default {
+ *     name: 'ai-overview',
+ *     description: 'Google AI Overview summary + cited links',
+ *     match: /google\.[a-z.]+\/search/,   // optional: hints it fits the URL
+ *     waitFor: () => boolean,             // optional: runs IN the page; the tool
+ *                                         //   waits for this to become true
+ *     extract: () => any,                 // required: runs IN the page (via
+ *                                         //   page.evaluate) and returns JSON
+ *   };
+ *
+ * IMPORTANT: `waitFor` and `extract` are serialized and executed in the browser
+ * context, so they must be self-contained — no closures over Node-side scope,
+ * no imports. Define any helpers inside the function body.
+ */
+import { readdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { pathToFileURL } from 'url';
+import { join } from 'path';
+import { getOutputPath } from './paths.js';
+const PLUGIN_EXT = /\.(mjs|cjs|js)$/;
+/** Candidate parser directories, project first then global. Existing only. */
+function parserDirs() {
+    const candidates = [
+        getOutputPath('parsers'),
+        getOutputPath('parsers', { global: true }),
+    ];
+    const dirs = [];
+    for (const d of candidates) {
+        if (!dirs.includes(d) && existsSync(d))
+            dirs.push(d);
+    }
+    return dirs;
+}
+export function parserSearchPaths() {
+    // Return intended locations even if they don't exist yet (for messaging).
+    const proj = getOutputPath('parsers');
+    const global = getOutputPath('parsers', { global: true });
+    return proj === global ? [proj] : [proj, global];
+}
+async function importPlugin(file) {
+    // Cache-bust so edited plugins reload without restarting the server.
+    const url = `${pathToFileURL(file).href}?t=${Date.now()}`;
+    const mod = await import(url);
+    const plugin = (mod.default ?? mod);
+    if (!plugin || typeof plugin.extract !== 'function') {
+        throw new Error(`Parser '${file}' must default-export an object with an extract() function`);
+    }
+    return plugin;
+}
+async function pluginFiles(dir) {
+    try {
+        return (await readdir(dir)).filter((f) => PLUGIN_EXT.test(f)).map((f) => join(dir, f));
+    }
+    catch {
+        return [];
+    }
+}
+/** List available plugins (project overrides global on name collision). */
+export async function listParsers(url) {
+    const byName = new Map();
+    for (const dir of parserDirs()) {
+        for (const file of await pluginFiles(dir)) {
+            try {
+                const p = await importPlugin(file);
+                const name = p.name || file.replace(/^.*\//, '').replace(PLUGIN_EXT, '');
+                if (byName.has(name))
+                    continue; // project scanned first wins
+                byName.set(name, {
+                    name,
+                    description: p.description,
+                    file,
+                    matches: url && p.match ? p.match.test(url) : undefined,
+                });
+            }
+            catch {
+                // Skip a broken plugin during listing rather than failing the whole call.
+            }
+        }
+    }
+    return [...byName.values()];
+}
+/** Load a single plugin by name. Throws if not found. */
+export async function loadParser(name) {
+    for (const dir of parserDirs()) {
+        for (const file of await pluginFiles(dir)) {
+            const p = await importPlugin(file);
+            const pname = p.name || file.replace(/^.*\//, '').replace(PLUGIN_EXT, '');
+            if (pname === name)
+                return p;
+        }
+    }
+    throw new Error(`Parser plugin '${name}' not found. Searched: ${parserSearchPaths().join(', ')}`);
+}
+//# sourceMappingURL=parser-plugins.js.map

package/build/helpers/parser-plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser-plugins.js","sourceRoot":"","sources":["../../src/helpers/parser-plugins.ts"],"names":[],"mappings":"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"}

package/build/helpers/paths.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Centralized path configuration for cdp-tools output directories
+ *
+ * All data defaults to working directory (<cwd>/.cdp-tools/).
+ * Use global: true to save to ~/.cdp-tools/ instead.
+ * If cwd is invalid (e.g., "/"), falls back to global automatically.
+ */
+import { z } from 'zod';
+declare const pathOptionsSchema: z.ZodObject<{
+    global: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    global?: boolean | undefined;
+}, {
+    global?: boolean | undefined;
+}>;
+interface PathConfig {
+    globalBase: string;
+    workingDirBase: string | null;
+    tempBase: string;
+}
+/**
+ * Initialize path configuration at startup.
+ * Called automatically on first path request, but can be called explicitly for early initialization.
+ */
+export declare function initializePaths(): PathConfig;
+/**
+ * Override the working-directory base at runtime.
+ * Needed because MCP clients (e.g. Claude Desktop) spawn one long-lived
+ * server process shared across projects — process.cwd() reflects wherever
+ * the client happened to launch from, not the project the user is in.
+ *
+ * @throws if dir does not exist or is not writable
+ */
+export declare function setWorkingDirOverride(dir: string): void;
+/**
+ * Get path for cdp-tools data.
+ * Defaults to working directory, use global: true for ~/.cdp-tools/
+ *
+ * @param segments - Path segments to join (e.g., 'logs', 'debug.log')
+ * @param options - { global: true } to use ~/.cdp-tools/ instead of cwd
+ * @returns Full path like /project/.cdp-tools/logs/debug.log
+ */
+export declare function getOutputPath(...args: [...string[]] | [...string[], z.infer<typeof pathOptionsSchema>]): string;
+/**
+ * Get config path with backwards compatibility.
+ * Checks cwd first (if valid and config exists there), then global.
+ *
+ * @returns Path to config.json
+ */
+export declare function getConfigPath(): string;
+/**
+ * Get path for saving new config.
+ *
+ * @param options - { global: true } to save to ~/.cdp-tools/ (default: working directory)
+ * @returns Path to config.json
+ */
+export declare function getConfigSavePath(options?: {
+    global?: boolean;
+}): string;
+/**
+ * Get path for temporary/ephemeral data.
+ * Uses system temp directory.
+ *
+ * @param segments - Path segments to join (e.g., 'a4-page.css')
+ * @returns Full path like /tmp/cdp-tools/a4-page.css
+ */
+export declare function getTempPath(...segments: string[]): string;
+/**
+ * Check if working directory storage is available (cwd is valid).
+ */
+export declare function hasWorkingDirStorage(): boolean;
+/** @deprecated Use getOutputPath() */
+export declare function getWorkingDirPath(...segments: string[]): string;
+/** @deprecated Use getOutputPath(...segments, { global: true }) */
+export declare function getGlobalPath(...segments: string[]): string;
+/** @deprecated Use getOutputPath() */
+export declare const getHomeOutputPath: typeof getGlobalPath;
+export {};
+//# sourceMappingURL=paths.d.ts.map

package/build/helpers/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/helpers/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,QAAA,MAAM,iBAAiB;;;;;;EAEZ,CAAC;AAEZ,UAAU,UAAU;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAsBD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,UAAU,CAW5C;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAMvD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,GAAG,IAAI,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC,GACxE,MAAM,CA0BR;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAatC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAUxE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAGzD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAG9C;AAGD,sCAAsC;AACtC,wBAAgB,iBAAiB,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAE/D;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAED,sCAAsC;AACtC,eAAO,MAAM,iBAAiB,sBAAgB,CAAC"}