/**
 * Unified Metadata Parser
 *
 * Single source of truth for parsing script metadata comments.
 * Used by both SDK (parseScript, getMetadata) and App (parseSnippet).
 *
 * @example
 * // In SDK:
 * import { parseMetadataComments } from './metadata-parser.js'
 * const { metadata, warnings } = parseMetadataComments(contents)
 *
 * // In App:
 * import { parseMetadataComments, VALID_METADATA_KEYS } from '@johnlindquist/kit/core/metadata-parser'
 * const { metadata, warnings } = parseMetadataComments(contents, { validate: false })
 */
import type { Metadata } from '../types/core.js';
/**
 * Warning generated when parsing metadata
 */
export interface MetadataWarning {
    line: number;
    key: string;
    message: string;
    suggestion?: string;
}
/**
 * Result from parsing metadata comments
 */
export interface ParseMetadataResult {
    metadata: Partial<Metadata>;
    warnings: MetadataWarning[];
    /** Raw key-value pairs before validation (includes invalid keys) */
    raw: Record<string, string | boolean | number>;
}
/**
 * Options for parseMetadataComments
 */
export interface ParseMetadataOptions {
    /** Whether to validate keys against VALID_METADATA_KEYS (default: true) */
    validate?: boolean;
    /** Maximum lines to scan for metadata (default: undefined = all lines) */
    maxLines?: number;
    /** Whether to stop at first non-comment line (default: false) */
    stopAtFirstNonComment?: boolean;
}
export declare const VALID_METADATA_KEYS: readonly ["author", "name", "description", "enter", "alias", "image", "emoji", "shortcut", "shortcode", "trigger", "snippet", "expand", "keyword", "pass", "group", "exclude", "watch", "log", "background", "system", "schedule", "index", "access", "response", "tag", "longRunning", "mcp", "timeout", "cache", "bin", "postfix"];
export type ValidMetadataKey = typeof VALID_METADATA_KEYS[number];
export declare const VALID_METADATA_KEYS_SET: ReadonlySet<string>;
/**
 * Parse metadata from comment lines in script content.
 *
 * Supports both `//` and `#` comment styles.
 * Handles multiline comments (skips them).
 * Returns structured warnings for unknown/invalid keys.
 *
 * @param contents - The script file contents
 * @param options - Parsing options
 * @returns Parsed metadata, warnings, and raw key-value pairs
 */
export declare function parseMetadataComments(contents: string, options?: ParseMetadataOptions): ParseMetadataResult;
/**
 * Simplified parser for snippets that stops at first non-comment line.
 * Returns both metadata and the remaining content after metadata lines.
 *
 * @param contents - The snippet file contents
 * @returns Parsed metadata and the snippet body
 */
export declare function parseSnippetMetadata(contents: string): {
    metadata: Partial<Metadata>;
    warnings: MetadataWarning[];
    snippetBody: string;
    snippetKey: string;
    postfix: boolean;
};