ctxr-cli 0.29.0 → 0.31.0

package/dist/core/mcp/tools/files.d.ts

@@ -0,0 +1,163 @@
+import type { StoreConfig } from '../../../config/schema.js';
+import { type GrepParams } from '../ripgrep.js';
+import type { WriteDeps } from '../sessions.js';
+import type { Snapshot } from '../sync.js';
+/**
+ * serve-the-store-over-mcp design.md D12 (remote-access spec, *`Read`,
+ * `Grep` and `Glob` give file-shaped access with Claude Code's parameters*):
+ * Claude Code's own file tools, by name and parameter, answering from the
+ * commit being served. Paths are store-relative (a leading `/` names the
+ * store root). What these tools may never read or return is one list, used
+ * both to refuse a named path and as ripgrep's exclusions.
+ */
+export declare const READ_DEFAULT_LIMIT = 2000;
+/** Everything these tools hide: the retrieval exclusions except the capture tier, plus configuration and `.git`. */
+export declare function hiddenPrefixes(config: StoreConfig): string[];
+/** A caller's path as a store-relative one; refused when it leaves the store or is hidden. `''` is the store root. */
+export declare function resolveStorePath(input: string, config: StoreConfig): string;
+/** What `Read` answers for, as one predicate: a note, a markdown capture, or the entry document. Grep and Glob return nothing else. */
+export declare function readablePath(rel: string, config: StoreConfig): boolean;
+export interface ReadArgs {
+    file_path: string;
+    offset?: number;
+    limit?: number;
+}
+export declare const READ_INPUT_SCHEMA: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly file_path: {
+            readonly type: 'string';
+            readonly description: 'The file to read, relative to the store root (a leading / means the store root), e.g. "projects/kestrel.md".';
+        };
+        readonly offset: {
+            readonly type: 'number';
+            readonly description: 'The line number to start reading from. Only provide if the file is too large to read at once.';
+        };
+        readonly limit: {
+            readonly type: 'number';
+            readonly description: 'The number of lines to read. Only provide if the file is too large to read at once.';
+        };
+    };
+    readonly required: readonly ['file_path'];
+};
+export declare function parseReadArgs(args: Record<string, unknown>): ReadArgs;
+export interface ReadResult {
+    file_path: string;
+    /** `cat -n` style: the line number, a tab, the line. */
+    content: string;
+    total_lines: number;
+    first_line: number;
+    last_line: number;
+    draft: boolean;
+    capture: boolean;
+    /** The note's page on the browsing surface, for citing; null for a capture or the entry document. */
+    url: string | null;
+}
+export declare function readTool(snapshot: Snapshot, write: WriteDeps, email: string, args: ReadArgs): Promise<ReadResult>;
+export declare function renderRead(data: unknown): string;
+export interface GrepArgs extends GrepParams {
+    head_limit?: number;
+    offset?: number;
+}
+export declare const GREP_INPUT_SCHEMA: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly pattern: {
+            readonly type: 'string';
+            readonly description: 'The regular expression pattern to search for in file contents';
+        };
+        readonly path: {
+            readonly type: 'string';
+            readonly description: 'File or directory to search in, relative to the store root. Defaults to the whole store.';
+        };
+        readonly glob: {
+            readonly type: 'string';
+            readonly description: 'Glob pattern to filter files (e.g. "*.md", "projects/**/*.md")';
+        };
+        readonly type: {
+            readonly type: 'string';
+            readonly description: 'File type to search (e.g. md). More efficient than glob for standard file types.';
+        };
+        readonly output_mode: {
+            readonly type: 'string';
+            readonly enum: readonly ['content', 'files_with_matches', 'count'];
+            readonly description: 'Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts.';
+        };
+        readonly '-i': {
+            readonly type: 'boolean';
+            readonly description: 'Case insensitive search';
+        };
+        readonly '-n': {
+            readonly type: 'boolean';
+            readonly description: 'Show line numbers in output (content mode; defaults to true)';
+        };
+        readonly '-A': {
+            readonly type: 'number';
+            readonly description: 'Number of lines to show after each match (content mode)';
+        };
+        readonly '-B': {
+            readonly type: 'number';
+            readonly description: 'Number of lines to show before each match (content mode)';
+        };
+        readonly '-C': {
+            readonly type: 'number';
+            readonly description: 'Number of lines to show before and after each match (content mode)';
+        };
+        readonly context: {
+            readonly type: 'number';
+            readonly description: 'Alias for -C';
+        };
+        readonly multiline: {
+            readonly type: 'boolean';
+            readonly description: 'Enable multiline mode where . matches newlines and patterns can span lines';
+        };
+        readonly head_limit: {
+            readonly type: 'number';
+            readonly description: 'Limit output to the first N lines/entries';
+        };
+        readonly offset: {
+            readonly type: 'number';
+            readonly description: 'Skip the first N lines/entries before applying head_limit';
+        };
+    };
+    readonly required: readonly ['pattern'];
+};
+export declare function parseGrepArgs(args: Record<string, unknown>): GrepArgs;
+export interface GrepResult {
+    output_mode: string;
+    lines: string[];
+    omitted: number;
+    /** Inbox files on session branches with an open pull request that match: captures awaiting approval. */
+    awaiting_approval: {
+        path: string;
+        branch: string;
+        lines: string[];
+    }[];
+}
+export declare function grepTool(snapshot: Snapshot, args: GrepArgs): Promise<GrepResult>;
+export declare function renderGrep(data: unknown): string;
+export interface GlobArgs {
+    pattern: string;
+    path?: string;
+}
+export declare const GLOB_INPUT_SCHEMA: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly pattern: {
+            readonly type: 'string';
+            readonly description: 'The glob pattern to match files against, e.g. "**/*.md" or "projects/**/*.md"';
+        };
+        readonly path: {
+            readonly type: 'string';
+            readonly description: 'The directory to search in, relative to the store root. Defaults to the whole store.';
+        };
+    };
+    readonly required: readonly ['pattern'];
+};
+export declare function parseGlobArgs(args: Record<string, unknown>): GlobArgs;
+export declare function globTool(snapshot: Snapshot, args: GlobArgs): Promise<{
+    files: string[];
+    omitted: number;
+}>;
+export declare function renderGlob(data: unknown): string;
+//# sourceMappingURL=files.d.ts.map

package/dist/core/mcp/tools/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/tools/files.ts"],"names":[],"mappings":"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"}

package/dist/core/mcp/tools/files.js

@@ -0,0 +1,265 @@
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { joinBaseUrl, noteRoute } from '../../browse/page-url.js';
+import { isUnderAnyPrefix } from '../../fs/prefix.js';
+import { admitsNotePath, excludedPrefixesFor } from '../../notes/list.js';
+import { CONFIG_FILE_NAME } from '../../root.js';
+import { draftVersion, findLocalDraft } from '../drafts.js';
+import { ToolRefusal } from '../jsonrpc.js';
+import { glob as ripgrepGlob, grep as ripgrepGrep } from '../ripgrep.js';
+/**
+ * serve-the-store-over-mcp design.md D12 (remote-access spec, *`Read`,
+ * `Grep` and `Glob` give file-shaped access with Claude Code's parameters*):
+ * Claude Code's own file tools, by name and parameter, answering from the
+ * commit being served. Paths are store-relative (a leading `/` names the
+ * store root). What these tools may never read or return is one list, used
+ * both to refuse a named path and as ripgrep's exclusions.
+ */
+export const READ_DEFAULT_LIMIT = 2000;
+const READ_MAX_LINE_CHARS = 2000;
+const GREP_MAX_LINES = 1000;
+/** The store's entry document, readable though it is not a note. */
+const ENTRY_DOCUMENT = 'AGENTS.md';
+/** Everything these tools hide: the retrieval exclusions except the capture tier, plus configuration and `.git`. */
+export function hiddenPrefixes(config) {
+    const captureRoot = config.ingest.capture_root.replace(/\/+$/, '');
+    return [...excludedPrefixesFor(config).filter((p) => p.replace(/\/+$/, '') !== captureRoot), CONFIG_FILE_NAME, '.git'];
+}
+/** A caller's path as a store-relative one; refused when it leaves the store or is hidden. `''` is the store root. */
+export function resolveStorePath(input, config) {
+    const cleaned = input.trim().replace(/\\/g, '/');
+    const normalized = path.posix.normalize(`/${cleaned}`).replace(/^\/+/, '').replace(/\/+$/, '');
+    if (normalized === '..' || normalized.startsWith('../') || cleaned.split('/').includes('..')) {
+        throw new ToolRefusal('mcp.path_outside_store', `"${input}" is outside the store.`);
+    }
+    if (normalized !== '' && isUnderAnyPrefix(normalized, hiddenPrefixes(config))) {
+        throw new ToolRefusal('mcp.path_not_readable', `"${normalized}" is not something these tools read (configuration, derived files and tool-owned folders are not).`);
+    }
+    return normalized;
+}
+/** What `Read` answers for, as one predicate: a note, a markdown capture, or the entry document. Grep and Glob return nothing else. */
+export function readablePath(rel, config) {
+    if (admitsNotePath(rel, config) || rel === ENTRY_DOCUMENT)
+        return true;
+    return rel.endsWith('.md') && isUnderAnyPrefix(rel, [config.ingest.capture_root]);
+}
+export const READ_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        file_path: { type: 'string', description: 'The file to read, relative to the store root (a leading / means the store root), e.g. "projects/kestrel.md".' },
+        offset: { type: 'number', description: 'The line number to start reading from. Only provide if the file is too large to read at once.' },
+        limit: { type: 'number', description: 'The number of lines to read. Only provide if the file is too large to read at once.' },
+    },
+    required: ['file_path'],
+};
+function positiveInteger(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0)
+        throw new ToolRefusal('mcp.invalid_arguments', `"${name}" must be a whole number.`);
+    return value;
+}
+export function parseReadArgs(args) {
+    if (typeof args.file_path !== 'string' || args.file_path.trim() === '')
+        throw new ToolRefusal('mcp.invalid_arguments', '"file_path" is required.');
+    return { file_path: args.file_path, offset: positiveInteger(args.offset, 'offset'), limit: positiveInteger(args.limit, 'limit') };
+}
+function numbered(text, offset, limit) {
+    const lines = text.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    const first = Math.max(1, offset ?? 1);
+    const count = limit ?? READ_DEFAULT_LIMIT;
+    const slice = lines.slice(first - 1, first - 1 + count);
+    const content = slice
+        .map((line, i) => `${String(first + i).padStart(6)}\t${line.length > READ_MAX_LINE_CHARS ? `${line.slice(0, READ_MAX_LINE_CHARS)}… (line truncated)` : line}`)
+        .join('\n');
+    return { content, total: lines.length, first, last: first + slice.length - 1 };
+}
+export async function readTool(snapshot, write, email, args) {
+    const config = snapshot.store.config;
+    const rel = resolveStorePath(args.file_path, config);
+    const captureRoot = config.ingest.capture_root;
+    const isCapture = isUnderAnyPrefix(rel, [captureRoot]);
+    const admitted = admitsNotePath(rel, config);
+    const draft = admitted ? await findLocalDraft(write, email) : null;
+    const drafted = draft === null ? null : await draftVersion(write, draft, rel);
+    if (drafted !== null) {
+        const n = numbered(drafted, args.offset, args.limit);
+        return { file_path: rel, content: n.content, total_lines: n.total, first_line: n.first, last_line: n.last, draft: true, capture: false, url: null };
+    }
+    if (!admitted && !isCapture && rel !== ENTRY_DOCUMENT) {
+        throw new ToolRefusal('mcp.path_not_readable', `"${rel}" is not a note, a capture or the entry document, so it cannot be read here.`);
+    }
+    const absolute = path.join(snapshot.store.root, rel);
+    const info = await lstat(absolute).catch(() => null);
+    if (info === null || (!info.isFile() && !info.isSymbolicLink()))
+        throw new ToolRefusal('mcp.file_not_found', `"${rel}" does not exist in the store.`);
+    // A link is never followed: a committed symlink named like a note could otherwise read anything the server can.
+    if (info.isSymbolicLink())
+        throw new ToolRefusal('mcp.path_not_readable', `"${rel}" is a symbolic link, which these tools do not follow.`);
+    const real = await realpath(absolute);
+    const root = await realpath(snapshot.store.root);
+    if (path.relative(root, real).startsWith('..'))
+        throw new ToolRefusal('mcp.path_outside_store', `"${rel}" is outside the store.`);
+    const n = numbered(await readFile(absolute, 'utf8'), args.offset, args.limit);
+    const url = admitted ? joinBaseUrl(write.baseUrl, noteRoute(rel)) : null;
+    return { file_path: rel, content: n.content, total_lines: n.total, first_line: n.first, last_line: n.last, draft: false, capture: isCapture, url };
+}
+export function renderRead(data) {
+    const r = data;
+    const notes = [];
+    if (r.draft)
+        notes.push('This is your pending draft of this note (awaiting approval), not the version in the store.');
+    if (r.capture)
+        notes.push('This is a capture: raw material not yet filed into a note. Do not present it as what the store says.');
+    if (r.url !== null)
+        notes.push(`${r.file_path}, at ${r.url}. Include this link when you cite the note.`);
+    if (r.last_line < r.total_lines)
+        notes.push(`Showing lines ${r.first_line}–${r.last_line} of ${r.total_lines}.`);
+    return [...notes.map((n) => `[${n}]`), r.content].join('\n');
+}
+export const GREP_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        pattern: { type: 'string', description: 'The regular expression pattern to search for in file contents' },
+        path: { type: 'string', description: 'File or directory to search in, relative to the store root. Defaults to the whole store.' },
+        glob: { type: 'string', description: 'Glob pattern to filter files (e.g. "*.md", "projects/**/*.md")' },
+        type: { type: 'string', description: 'File type to search (e.g. md). More efficient than glob for standard file types.' },
+        output_mode: { type: 'string', enum: ['content', 'files_with_matches', 'count'], description: 'Output mode: "content" shows matching lines, "files_with_matches" shows file paths (default), "count" shows match counts.' },
+        '-i': { type: 'boolean', description: 'Case insensitive search' },
+        '-n': { type: 'boolean', description: 'Show line numbers in output (content mode; defaults to true)' },
+        '-A': { type: 'number', description: 'Number of lines to show after each match (content mode)' },
+        '-B': { type: 'number', description: 'Number of lines to show before each match (content mode)' },
+        '-C': { type: 'number', description: 'Number of lines to show before and after each match (content mode)' },
+        context: { type: 'number', description: 'Alias for -C' },
+        multiline: { type: 'boolean', description: 'Enable multiline mode where . matches newlines and patterns can span lines' },
+        head_limit: { type: 'number', description: 'Limit output to the first N lines/entries' },
+        offset: { type: 'number', description: 'Skip the first N lines/entries before applying head_limit' },
+    },
+    required: ['pattern'],
+};
+export function parseGrepArgs(args) {
+    const invalid = (message) => new ToolRefusal('mcp.invalid_arguments', message);
+    if (typeof args.pattern !== 'string' || args.pattern === '')
+        throw invalid('"pattern" is required.');
+    const out = { pattern: args.pattern };
+    for (const key of ['path', 'glob', 'type']) {
+        if (args[key] !== undefined && args[key] !== null) {
+            if (typeof args[key] !== 'string')
+                throw invalid(`"${key}" must be a string.`);
+            out[key] = args[key];
+        }
+    }
+    if (args.output_mode !== undefined && args.output_mode !== null) {
+        if (args.output_mode !== 'content' && args.output_mode !== 'files_with_matches' && args.output_mode !== 'count')
+            throw invalid('"output_mode" is content, files_with_matches or count.');
+        out.output_mode = args.output_mode;
+    }
+    for (const key of ['-i', '-n', 'multiline']) {
+        if (args[key] !== undefined && args[key] !== null) {
+            if (typeof args[key] !== 'boolean')
+                throw invalid(`"${key}" must be true or false.`);
+            out[key] = args[key];
+        }
+    }
+    for (const key of ['-A', '-B', '-C', 'context', 'head_limit', 'offset']) {
+        const value = positiveInteger(args[key], key);
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+export async function grepTool(snapshot, args) {
+    const config = snapshot.store.config;
+    const searchPath = args.path === undefined ? null : resolveStorePath(args.path, config) || null;
+    const outcome = await ripgrepGrep(snapshot.store.root, args, searchPath, hiddenPrefixes(config));
+    if (outcome.kind === 'error')
+        throw new ToolRefusal('mcp.search_failed', `The search could not run: ${outcome.message}.`);
+    // design.md D12: Grep returns only what Read would read, so it never prints a file Read refuses.
+    const entries = outcome.kind === 'ok' ? outcome.entries.filter((e) => e.path === null || readablePath(e.path, config)) : [];
+    const all = [];
+    for (const e of entries) {
+        if (e.path === null) {
+            if (all.length > 0 && all[all.length - 1] !== '--')
+                all.push(e.rest ?? '--');
+        }
+        else if (e.rest === null)
+            all.push(e.path);
+        else
+            all.push(`${e.path}${/^\d+[-]/.test(e.rest) ? '-' : ':'}${e.rest}`);
+    }
+    while (all[all.length - 1] === '--')
+        all.pop();
+    const start = args.offset ?? 0;
+    const limit = Math.min(args.head_limit ?? GREP_MAX_LINES, GREP_MAX_LINES);
+    const lines = all.slice(start, start + limit);
+    // design.md D12: the duplicate `find` reveals, revealed here too. JavaScript's engine stands in for ripgrep's
+    // over a handful of small files; a pattern it cannot compile simply matches none of them.
+    const awaiting = [];
+    let regex = null;
+    try {
+        regex = new RegExp(args.pattern, args['-i'] === true ? 'i' : '');
+    }
+    catch {
+        regex = null;
+    }
+    if (regex !== null) {
+        for (const capture of snapshot.pending) {
+            if (searchPath !== null && !isUnderAnyPrefix(capture.path, [searchPath]))
+                continue;
+            const matching = capture.text
+                .split('\n')
+                .map((line, i) => ({ line, n: i + 1 }))
+                .filter(({ line }) => regex.test(line))
+                .slice(0, 3)
+                .map(({ line, n }) => `${n}:${line}`);
+            if (matching.length > 0)
+                awaiting.push({ path: capture.path, branch: capture.branch, lines: matching });
+        }
+    }
+    return { output_mode: args.output_mode ?? 'files_with_matches', lines, omitted: Math.max(0, all.length - start - lines.length), awaiting_approval: awaiting };
+}
+export function renderGrep(data) {
+    const r = data;
+    const out = r.lines.length > 0 ? [...r.lines] : ['No matches found.'];
+    if (r.omitted > 0)
+        out.push(`[${r.omitted} more not shown; use offset or narrow the search]`);
+    if (r.awaiting_approval.length > 0) {
+        out.push('', '[Captures awaiting approval, not yet in the store:]');
+        for (const c of r.awaiting_approval)
+            out.push(...c.lines.map((l) => `${c.path} (awaiting approval):${l}`));
+    }
+    return out.join('\n');
+}
+export const GLOB_INPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        pattern: { type: 'string', description: 'The glob pattern to match files against, e.g. "**/*.md" or "projects/**/*.md"' },
+        path: { type: 'string', description: 'The directory to search in, relative to the store root. Defaults to the whole store.' },
+    },
+    required: ['pattern'],
+};
+export function parseGlobArgs(args) {
+    if (typeof args.pattern !== 'string' || args.pattern === '')
+        throw new ToolRefusal('mcp.invalid_arguments', '"pattern" is required.');
+    if (args.path !== undefined && args.path !== null && typeof args.path !== 'string')
+        throw new ToolRefusal('mcp.invalid_arguments', '"path" must be a string.');
+    return { pattern: args.pattern, ...(typeof args.path === 'string' ? { path: args.path } : {}) };
+}
+export async function globTool(snapshot, args) {
+    const config = snapshot.store.config;
+    const searchPath = args.path === undefined ? null : resolveStorePath(args.path, config) || null;
+    const outcome = await ripgrepGlob(snapshot.store.root, args.pattern, searchPath, hiddenPrefixes(config));
+    if (outcome.kind === 'error')
+        throw new ToolRefusal('mcp.search_failed', `The file listing could not run: ${outcome.message}.`);
+    const files = outcome.kind === 'ok' ? outcome.entries.map((e) => e.path).filter((p) => p !== null && readablePath(p, config)) : [];
+    return { files: files.slice(0, GREP_MAX_LINES), omitted: Math.max(0, files.length - GREP_MAX_LINES) };
+}
+export function renderGlob(data) {
+    const r = data;
+    if (r.files.length === 0)
+        return 'No files found';
+    return [...r.files, ...(r.omitted > 0 ? [`[${r.omitted} more not shown; narrow the pattern]`] : [])].join('\n');
+}
+//# sourceMappingURL=files.js.map

package/dist/core/mcp/tools/files.js.map

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

package/dist/core/mcp/tools/find.d.ts

@@ -0,0 +1,82 @@
+import type { Snapshot } from '../sync.js';
+/**
+ * remote-access spec, *`find` stands in for a client's own content
+ * matching*; context-retrieval's bounded exception. Literal,
+ * case-insensitive substring matching over the notes the store's
+ * enumeration admits, in path order, with no score. Captures — inbox files
+ * on the default branch and on pending `capture/` branches — come back in
+ * `unfiled`, never among the notes (context-ingest's exception, design.md
+ * D6). With no text, the catalog as a map to pick selectors from.
+ */
+export declare const MAX_LINES_PER_HIT = 3;
+export declare const MAX_LINE_CHARS = 240;
+export declare const DEFAULT_MAX_MATCHES = 25;
+export declare const DEFAULT_MAX_MAP_NOTES = 500;
+export declare const MAX_RESULTS = 1000;
+export interface FindArgs {
+    text?: string;
+    under?: string;
+    max?: number;
+}
+export interface MatchingLine {
+    line: number;
+    text: string;
+}
+export interface NoteHit {
+    path: string;
+    gloss: string;
+    lines: MatchingLine[];
+    matching_lines: number;
+    url: string | null;
+}
+export interface UnfiledHit {
+    path: string;
+    lines: MatchingLine[];
+    matching_lines: number;
+    pending_merge: boolean;
+    branch: string | null;
+}
+export type FindResult = {
+    mode: 'match';
+    text: string;
+    notes: NoteHit[];
+    notes_omitted: number;
+    unfiled: UnfiledHit[];
+    unfiled_omitted: number;
+} | {
+    mode: 'map';
+    sections: {
+        id: string;
+        notes: {
+            path: string;
+            gloss: string;
+            url: string | null;
+        }[];
+    }[];
+    notes_omitted: number;
+};
+/**
+ * Plain on purpose: type, description and required only. Some clients (Gemini) accept a narrow subset of JSON
+ * Schema and drop a tool whose schema uses more; every limit is enforced by `parseFindArgs` instead.
+ */
+export declare const FIND_INPUT_SCHEMA: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly text: {
+            readonly type: 'string';
+            readonly description: 'Literal text to look for, case-insensitive. Omit it to get the map of the store instead.';
+        };
+        readonly under: {
+            readonly type: 'string';
+            readonly description: 'Only look under this folder of the store, e.g. "projects/".';
+        };
+        readonly max: {
+            readonly type: 'integer';
+            readonly description: "How many notes to return (default 25 when matching, 500 for the map).";
+        };
+    };
+};
+export declare function parseFindArgs(args: Record<string, unknown>): FindArgs;
+/** `baseUrl` is `serve.base_url` from the configuration `serve` loaded: links point at the browsing surface it answers. */
+export declare function find(snapshot: Snapshot, args: FindArgs, baseUrl: string | undefined): Promise<FindResult>;
+//# sourceMappingURL=find.d.ts.map

package/dist/core/mcp/tools/find.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/tools/find.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,WAAW,OAAO,CAAC;AAGhC,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACxH;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,EAAE,CAAA;KAAE,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAErI;;;GAGG;AACH,eAAO,MAAM,iBAAiB;aAC5B,IAAI,EAAE,QAAQ;aACd,UAAU;iBACR,IAAI;qBAAI,IAAI,EAAE,QAAQ;qBAAE,WAAW,EAAE,0FAA0F;;iBAC/H,KAAK;qBAAI,IAAI,EAAE,QAAQ;qBAAE,WAAW,EAAE,6DAA6D;;iBACnG,GAAG;qBAAI,IAAI,EAAE,SAAS;qBAAE,WAAW;;;CAE7B,CAAC;AAEX,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,CAmBrE;AAmBD,2HAA2H;AAC3H,wBAAsB,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAwD/G"}