@maci0/dsh-caveman 0.16.2

package/lib/modes.js

@@ -0,0 +1,126 @@
+/**
+ * Caveman's level model: the accepted levels, their normalization, the
+ * mode-specific filter over the `caveman` skill body, and the instruction
+ * block the plugin injects into the system prompt.
+ *
+ * Levels mirror upstream (`JuliusBrussee/caveman`, MIT): lite, full, ultra
+ * and the three wenyan variants. Unlike ponytail there is no session-only
+ * level: every level persists. The one addition over upstream is the
+ * `wenyan` shorthand for `wenyan-full`, accepted by the `/caveman` command.
+ *
+ * @module dsh-caveman/modes
+ */
+/** Every accepted level; all persist as a default. */
+export const RUNTIME_MODES = [
+    'off',
+    'lite',
+    'full',
+    'ultra',
+    'wenyan-lite',
+    'wenyan-full',
+    'wenyan-ultra',
+];
+/** Level used when neither config nor environment sets one. */
+export const DEFAULT_MODE = 'full';
+/**
+ * Normalize a value to a level that may be persisted as a default.
+ * @param value - candidate level from a config field, environment, or command.
+ * @returns the canonical runtime level, or `undefined` when unrecognized.
+ */
+export function normalizeMode(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    return RUNTIME_MODES.find((mode) => mode === normalized);
+}
+/**
+ * Whether a whole message is a deactivation command.
+ *
+ * "stop caveman" / "normal mode" turn caveman off, but only as a standalone
+ * command: matching the phrase anywhere in a message turned it off mid-task for
+ * ordinary requests like "add a normal mode toggle", so the whole trimmed
+ * message must be the command, ignoring case and trailing punctuation.
+ * @param text - user message text.
+ * @returns whether the message is the deactivation command.
+ */
+export function isDeactivationCommand(text) {
+    const normalized = String(text ?? '').trim().toLowerCase().replace(/[.!?\s]+$/, '');
+    return normalized === 'stop caveman' || normalized === 'normal mode';
+}
+/**
+ * Resolve a human `/caveman` argument to a level, including the `wenyan`
+ * shorthand for `wenyan-full` (upstream: `/caveman wenyan` means full 文言文).
+ * @param input - trimmed, lowercased command input.
+ * @returns the canonical level, or `undefined` when unrecognized.
+ */
+export function normalizeCommandMode(input) {
+    if (input === 'wenyan')
+        return 'wenyan-full';
+    return normalizeMode(input);
+}
+/**
+ * Resolve the configured level and the source that decided it.
+ *
+ * Order: this plugin's config field, then `CAVEMAN_DEFAULT_MODE`, then the
+ * upstream config file (`~/.config/caveman/config.json`), then `full`.
+ * @param sources - injectable overrides for tests.
+ * @returns the level and its source.
+ */
+export function resolveDefaultMode(sources = {}) {
+    const configured = normalizeMode(sources.configured);
+    if (configured !== undefined)
+        return { mode: configured, source: 'settings' };
+    const envMode = normalizeMode((sources.env ?? process.env)['CAVEMAN_DEFAULT_MODE']);
+    if (envMode !== undefined)
+        return { mode: envMode, source: 'env' };
+    const fileMode = normalizeMode(sources.configFile?.defaultMode);
+    if (fileMode !== undefined)
+        return { mode: fileMode, source: 'config-file' };
+    return { mode: DEFAULT_MODE, source: 'default' };
+}
+/**
+ * Drop the intensity-table rows and worked examples that belong to other
+ * levels.
+ *
+ * Only the intensity table rows and worked examples are mode-specific, and both
+ * are keyed by a level name. A bullet whose label is not a level (e.g.
+ * "Never drop not/never/no/only/except ...") is a normal rule and stays
+ * verbatim; the quoted-value requirement on examples is what keeps a rule that
+ * merely starts with a level word from being dropped in every other mode.
+ * @param body - markdown of the `caveman` skill, frontmatter already removed.
+ * @param mode - the level to keep.
+ * @returns the body with other levels' rows and examples removed.
+ */
+export function filterSkillBodyForMode(body, mode) {
+    const effective = normalizeMode(mode) ?? DEFAULT_MODE;
+    return String(body ?? '')
+        .split(/\r?\n/)
+        .filter((line) => {
+        const tableLabel = /^\|\s*\*\*(.+?)\*\*\s*\|/.exec(line);
+        if (tableLabel?.[1] !== undefined) {
+            const labelMode = normalizeMode(tableLabel[1].trim());
+            if (labelMode !== undefined)
+                return labelMode === effective;
+        }
+        const exampleLabel = /^-\s*([^:]+):\s*"/.exec(line);
+        if (exampleLabel?.[1] !== undefined) {
+            const labelMode = normalizeMode(exampleLabel[1].trim());
+            if (labelMode !== undefined)
+                return labelMode === effective;
+        }
+        return true;
+    })
+        .join('\n');
+}
+/**
+ * Build the exact text the system prompt carries for one level.
+ * @param input - the active level and the skill body.
+ * @returns the instruction block, or `''` when the level is `off`.
+ */
+export function buildModeInstructions(input) {
+    const { mode } = input;
+    if (mode === 'off')
+        return '';
+    const effective = normalizeMode(mode) ?? DEFAULT_MODE;
+    return `CAVEMAN MODE ACTIVE — level: ${effective}\n\n${filterSkillBodyForMode(input.skillBody, effective)}`;
+}

package/lib/skills.js

@@ -0,0 +1,177 @@
+/**
+ * The bundled caveman skills as a `ctx.skills` provider.
+ *
+ * Skills are read from this package's `skills/<name>/SKILL.md`, so the same
+ * files stay the single source of truth for both the always-on ruleset (which
+ * filters the `caveman` body per level) and the on-demand skills.
+ *
+ * @module dsh-caveman/skills
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { BUNDLED_SKILL_RANK, isSkillName } from '@deepseek-ai/dsh-skill';
+import { parseFrontmatterAsync } from './frontmatter.js';
+/** Provider name inside the skill registry. */
+const PROVIDER_NAME = 'caveman';
+/** Instruction file every skill directory must carry. */
+const INSTRUCTION_FILE = 'SKILL.md';
+/**
+ * Frontmatter keys that already have a first-class home on the summary: they
+ * are projected into `name`, `description`, `whenToUse`, and `invocation`, so
+ * repeating them in `metadata` would only duplicate the domain model.
+ */
+const PROJECTED_KEYS = new Set([
+    'name',
+    'description',
+    'whenToUse',
+    'disable-model-invocation',
+    'user-invocable',
+]);
+/** Read a frontmatter value as a non-empty trimmed string. */
+function readString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * Read and parse one skill file. Shared by discovery and direct loads so a
+ * single file enforces the name/description/frontmatter rules everywhere.
+ * @param path - absolute path of the `SKILL.md` file.
+ * @param onWarn - optional non-fatal problem sink.
+ * @param entryName - directory name fallback when frontmatter omits `name`.
+ * @returns the parsed skill, or `undefined` with a warning when invalid.
+ */
+async function readSkillFile(path, onWarn, entryName) {
+    let source;
+    try {
+        source = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        // A directory without an instruction file is a broken skill, not an empty
+        // one: `discoverSkills` promises it reaches the same sink as every other
+        // skipped skill.
+        onWarn?.(`cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = await parseFrontmatterAsync(source);
+    }
+    catch (error) {
+        onWarn?.(`skipping ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    const fallback = entryName ?? basename(path);
+    const name = readString(parsed.data['name']) || fallback;
+    const description = readString(parsed.data['description']);
+    const whenToUse = readString(parsed.data['whenToUse']);
+    if (!isSkillName(name)) {
+        onWarn?.(`skipping ${path}: "${name}" is not a valid kebab-case skill name`);
+        return undefined;
+    }
+    if (description === '') {
+        onWarn?.(`skipping ${path}: frontmatter has no description`);
+        return undefined;
+    }
+    const metadata = {};
+    for (const [key, value] of Object.entries(parsed.data)) {
+        if (!PROJECTED_KEYS.has(key))
+            metadata[key] = value;
+    }
+    return {
+        name,
+        description,
+        ...(whenToUse === '' ? {} : { whenToUse }),
+        // The canonical keys, defaulted the documented way: only an explicit `true`
+        // disables model invocation, only an explicit `false` disables user
+        // invocation.
+        invocation: {
+            modelInvocable: parsed.data['disable-model-invocation'] !== true,
+            userInvocable: parsed.data['user-invocable'] !== false,
+        },
+        content: parsed.body.trim(),
+        metadata,
+        path,
+        directory: dirname(path),
+    };
+}
+/**
+ * Read every valid skill directory under `skillsDir`.
+ *
+ * A missing directory, a directory without `SKILL.md`, a file whose frontmatter
+ * the reader refuses, and a file with a missing description are reported
+ * through `onWarn` and skipped: one broken file must not cost the catalog its
+ * other skills.
+ * @param skillsDir - directory holding one subdirectory per skill.
+ * @param onWarn - optional non-fatal problem sink.
+ * @returns the parsed skills, sorted by name.
+ */
+export async function discoverSkills(skillsDir, onWarn) {
+    let entries;
+    try {
+        entries = await readdir(skillsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        onWarn?.(`cannot read skills directory ${skillsDir}: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const path = join(skillsDir, entry.name, INSTRUCTION_FILE);
+        const skill = await readSkillFile(path, onWarn, entry.name);
+        if (skill !== undefined)
+            skills.push(skill);
+    }
+    return skills.sort((left, right) => left.name.localeCompare(right.name));
+}
+/**
+ * Build the provider the skill registry mounts.
+ * @param options - skills directory and the non-fatal problem sink.
+ * @returns a provider whose candidates are summaries and whose bodies come from disk.
+ */
+export function createSkillProvider(options) {
+    const summaryOf = (skill) => ({
+        path: skill.path,
+        name: skill.name,
+        description: skill.description,
+        ...(skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse }),
+        invocation: skill.invocation,
+        source: 'bundled',
+        provider: PROVIDER_NAME,
+        resourceBase: { kind: 'directory', path: skill.directory },
+    });
+    return {
+        name: PROVIDER_NAME,
+        async list(lookup = {}) {
+            lookup.signal?.throwIfAborted();
+            let complete = true;
+            const skills = await discoverSkills(options.skillsDir, (message) => {
+                complete = false;
+                options.onWarn?.(message);
+            });
+            lookup.signal?.throwIfAborted();
+            const candidates = skills.map((skill) => ({
+                ...summaryOf(skill),
+                rank: BUNDLED_SKILL_RANK,
+                locator: skill.path,
+                metadata: skill.metadata,
+            }));
+            return complete ? candidates : { candidates, complete: false };
+        },
+        async get(candidate, lookup = {}) {
+            if (typeof candidate.locator !== 'string')
+                return undefined;
+            lookup.signal?.throwIfAborted();
+            // Read the locator directly: one file instead of a full re-discovery.
+            // The directory name is the fallback discovery used, so a skill whose
+            // frontmatter omits `name` loads under the name `list` reported. The
+            // name check keeps a stale candidate (path reused by another skill) from
+            // loading under the wrong identity.
+            const skill = await readSkillFile(candidate.locator, options.onWarn, basename(dirname(candidate.locator)));
+            lookup.signal?.throwIfAborted();
+            if (skill === undefined || skill.name !== candidate.name)
+                return undefined;
+            return { ...summaryOf(skill), content: skill.content, metadata: skill.metadata };
+        },
+    };
+}

package/lib/types/compress-detect.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Detect whether a file is natural language (compressible) or code/config.
+ *
+ * TypeScript port of `skills/caveman-compress/scripts/detect.py` (MIT,
+ * © JuliusBrussee). The Python original is dropped: the ported pipeline runs
+ * in-process with no `python3` requirement.
+ *
+ * @module dsh-caveman/compress-detect
+ */
+/** File classification. */
+export type FileType = 'natural_language' | 'code' | 'config' | 'unknown';
+/**
+ * Classify a file as natural language, code, config, or unknown.
+ * @param basename - file basename (extension rules key off this).
+ * @param readText - reads the file when content sniffing is needed; throw to signal unreadable.
+ * @returns the classification.
+ */
+export declare function detectFileType(basename: string, readText?: () => string): FileType;

package/lib/types/compress-files.d.ts

@@ -0,0 +1,76 @@
+/**
+ * File handling for the compress pipeline: sensitive path refusal, atomic
+ * writes, backups, and source reading.
+ *
+ * TypeScript port of the non-model parts of
+ * `skills/caveman-compress/scripts/compress.py` (MIT, © JuliusBrussee).
+ * The `callClaude` half is deliberately not ported: this plugin compresses
+ * with deterministic local rules instead (see `compress-rules.ts`). The
+ * Python original is dropped.
+ *
+ * @module dsh-caveman/compress-files
+ */
+/**
+ * Packaged default for the `maxFileSize` cap (500000 bytes, ~500 KB), used when
+ * the plugin row does not override it. `apply` validates the configured value
+ * and threads it through the pipeline; this is only the default.
+ */
+export declare const MAX_FILE_SIZE = 500000;
+/**
+ * Heuristic denylist for files that must never be rewritten by a tool that
+ * ships bytes to a model. Fail loudly rather than exfiltrate.
+ * @param filePath - absolute file path.
+ * @returns true when the path looks sensitive.
+ */
+export declare function isSensitivePath(filePath: string): boolean;
+/**
+ * Out-of-tree backup dir for a file, keyed by its parent dir name, kept
+ * outside the source tree so skill auto-loaders don't re-ingest backups.
+ * @param filePath - absolute source path.
+ * @returns the backup directory.
+ */
+export declare function backupDirFor(filePath: string): string;
+/**
+ * Backup file path for a source file.
+ * @param filePath - absolute source path.
+ * @returns the `.original.md` backup path.
+ */
+export declare function backupPathFor(filePath: string): string;
+/** A write syscall-shaped function: bytes written, possibly fewer than asked. */
+export type WriteCall = (fd: number, buffer: Buffer, offset: number, length: number) => number;
+/**
+ * Write bytes atomically: sibling temp file, fsync, rename. Loops over short
+ * writes so the temp file is never a truncated prefix of `data`. Preserves the
+ * destination's permission bits across the swap.
+ * @param filePath - destination path.
+ * @param data - bytes to write.
+ * @param write - write syscall seam; defaults to `fs.writeSync`.
+ * @param exclusive - publish a backup only if its destination does not exist.
+ */
+export declare function writeBytesAtomic(filePath: string, data: Buffer, write?: WriteCall, exclusive?: boolean): void;
+/**
+ * Write text atomically as UTF-8, preserving the document's line terminator.
+ * @param filePath - destination path.
+ * @param text - text with `\n` line endings.
+ * @param newline - line terminator to emit.
+ */
+export declare function writeTextAtomic(filePath: string, text: string, newline?: '\n' | '\r\n'): void;
+/** A source file read exactly: decoded text, line terminator, raw bytes. */
+export interface SourceFile {
+    readonly text: string;
+    readonly newline: '\n' | '\r\n';
+    readonly raw: Buffer;
+    /** True when the file started with a UTF-8 BOM, stripped from `text`. */
+    readonly bom: boolean;
+}
+/**
+ * Read a source file strictly as UTF-8. A file that cannot be decoded
+ * exactly is refused: the round trip would destroy bytes.
+ *
+ * A leading BOM is detected from the raw bytes and reported separately: the
+ * decoder drops it, and the caller re-attaches it when writing so the byte
+ * survives the round trip.
+ * @param filePath - absolute source path.
+ * @returns text (LF-normalized), terminator, raw bytes for the backup, BOM flag.
+ */
+export declare function readSource(filePath: string): SourceFile;

package/lib/types/compress-pipeline.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The compress pipeline: detect, guard, rewrite locally, validate, back up,
+ * and write. TypeScript port of the orchestration in
+ * `skills/caveman-compress/scripts/compress.py` (MIT, © JuliusBrussee) with
+ * one deliberate difference: the rewrite step uses deterministic local rules
+ * (`compress-rules.ts`) instead of a model call, so no file bytes ever leave
+ * the machine and no API key or CLI is needed.
+ *
+ * Fail-closed throughout: sensitive paths refuse, oversized files refuse,
+ * non-UTF-8 refuses, an existing backup aborts, a candidate that is not
+ * smaller aborts, and a candidate that fails validation aborts. The live
+ * file is written only after a passing validation.
+ *
+ * @module dsh-caveman/compress-pipeline
+ */
+/** Why a compression run refused or failed. */
+export type CompressOutcome = {
+    readonly ok: true;
+    readonly backupPath: string;
+    readonly originalChars: number;
+    readonly compressedChars: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Compress one file in place, keeping an out-of-tree backup.
+ * @param inputPath - file to compress.
+ * @param maxFileSize - configured size cap in bytes; defaults to the packaged 500000.
+ * @returns the outcome; the file is untouched unless `ok` is true.
+ */
+export declare function compressFile(inputPath: string, maxFileSize?: number): CompressOutcome;

package/lib/types/compress-rules.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deterministic local compression rules: the caveman style without a model.
+ *
+ * This replaces the `callClaude` half of
+ * `skills/caveman-compress/scripts/compress.py` (MIT, © JuliusBrussee),
+ * which this plugin deliberately does not port: shipping file bytes to a
+ * third-party model for a local rewrite is the "dumb feature" this port
+ * leaves out. Everything else (detect, validate, file handling) is ported
+ * faithfully; only the rewrite step is local and rule-based.
+ *
+ * Rules mirror the skill's Compression Rules section: drop articles, filler,
+ * pleasantries, hedging, and connective fluff; shorten redundant phrasing;
+ * keep code/URLs/paths/commands/technical terms/numbers byte-identical;
+ * never touch headings. Code spans (fenced, indented, inline) are masked
+ * before rewriting and restored after, so prose rules cannot reach them.
+ *
+ * @module dsh-caveman/compress-rules
+ */
+/**
+ * Mask fenced and indented code blocks with opaque markers.
+ *
+ * The output is assembled from the *gaps between* blocks instead of one string
+ * per line: a document with no code returns the input string itself, and a
+ * document with three blocks pushes a handful of segments rather than tens of
+ * thousands of line references and then joins them all. The result is
+ * identical: each segment is a run of whole lines and the join puts the same
+ * `\n` separators back.
+ * @param text - markdown body.
+ * @returns masked text plus the blocks for restoration.
+ */
+export declare function maskCodeBlocks(text: string): {
+    masked: string;
+    blocks: string[];
+};
+/**
+ * Restore masked code blocks exactly; fail closed on tampering.
+ * @param text - rewritten text with markers.
+ * @param blocks - blocks from {@link maskCodeBlocks}.
+ * @returns text with code restored.
+ */
+export declare function restoreCodeBlocks(text: string, blocks: string[]): string;
+/**
+ * Compress one prose line: drop fluff, tighten phrasing, collapse space.
+ * Inline code spans (`` `...` ``) are masked first so rules skip them.
+ * @param line - a single non-heading, non-code line.
+ * @returns the compressed line.
+ */
+export declare function compressLine(line: string): string;
+/**
+ * Compress a markdown body with local rules. Headings pass through
+ * byte-identical; list markers and table pipes are preserved; everything
+ * else goes through {@link compressLine}. Empty results fall back to the
+ * original line so structure never collapses.
+ * @param body - markdown body (frontmatter already removed).
+ * @returns the compressed body.
+ */
+export declare function compressBody(body: string): string;
+/**
+ * Whether the candidate actually compresses the body (strictly smaller).
+ * Guard against a rewrite that validates structurally but saves nothing.
+ * @param candidate - compressed body.
+ * @param body - original body.
+ * @returns true when strictly smaller.
+ */
+export declare function isSmaller(candidate: string, body: string): boolean;

package/lib/types/compress-validate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Structural validation of a compressed file against its original.
+ *
+ * TypeScript port of `skills/caveman-compress/scripts/validate.py` (MIT,
+ * © JuliusBrussee). Same extractors, same six validators, same fail-closed
+ * posture: headings/code/URLs/paths/inline-code must survive byte-identical,
+ * bullets only warn on drift. The Python original is dropped.
+ *
+ * @module dsh-caveman/compress-validate
+ */
+/** Outcome of validating one original/compressed pair. */
+export interface ValidationResult {
+    readonly isValid: boolean;
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+}
+export declare function extractHeadings(text: string): [string, string][];
+/**
+ * Every fenced and indented code block, in document order.
+ *
+ * The masker already owns the definition of "code block" for the rewriter; the
+ * validator reuses it so both agree on what must survive byte-identical.
+ * @param text - markdown body.
+ * @returns the block texts.
+ */
+export declare function extractCodeBlocks(text: string): string[];
+export declare function extractUrls(text: string): Set<string>;
+export declare function extractPaths(text: string): Set<string>;
+export declare function extractInlineCodes(text: string): string[];
+/**
+ * Validate a compressed candidate against its original.
+ * @param original - original file text.
+ * @param compressed - compressed candidate text.
+ * @returns errors (fail-closed) and warnings (drift notes).
+ */
+export declare function validate(original: string, compressed: string): ValidationResult;

package/lib/types/frontmatter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Frontmatter reader for the bundled `SKILL.md` files and the compress
+ * pipeline.
+ *
+ * The fast path is a local reader for the flat subset those files use:
+ * `key: value` with a plain, single-quoted, or double-quoted scalar, and `>`/`|`
+ * block scalars in all three chomping forms. It claims only forms it can prove.
+ * A nested map, a list, a flow collection, a key form it does not recognise,
+ * or any other shape it is not sure about falls through to `yaml`.
+ *
+ * "Prove" is the whole contract, so the claimed subset is deliberately narrow:
+ * every line of the block must be a blank line, a column-0 comment, or
+ * `SIMPLE_KEY: value` with a key the YAML core schema leaves a string and no
+ * repeated key; a block that is anything else (a bare scalar, a sequence, an
+ * explicit `?` key, an indented continuation) is refused rather than guessed.
+ * {@link NON_STRING} is the YAML core schema's own resolution set copied out of
+ * `yaml/dist/schema/core`, so a value it does not match is provably a string,
+ * and a value it does match falls back instead of being read as one.
+ *
+ * The fallback is the contract, not an afterthought: `yaml` is never imported
+ * at module scope, so a catalog of flat files (every bundled skill) never pays
+ * the library's module-load cost. {@link parseFrontmatterAsync} loads it with a
+ * dynamic `import('yaml')`; the synchronous {@link parseFrontmatter} loads it
+ * with a lazy `createRequire` for the callers that cannot await.
+ *
+ * Behaviour matches the previous `yaml`-only reader: a block that is not a YAML
+ * mapping at all (a bare scalar, a sequence, an empty block) yields no keys and
+ * keeps the body, and a block that is malformed YAML throws, which
+ * `readSkillFile` turns into a warning and a skipped skill.
+ *
+ * @module dsh-caveman/frontmatter
+ */
+/** Parsed frontmatter plus the markdown body that follows it. */
+export interface Frontmatter {
+    /** The verbatim frontmatter block including both delimiters, or `''` when absent. */
+    readonly raw: string;
+    readonly data: Readonly<Record<string, unknown>>;
+    /** Everything after the closing delimiter, or the whole source when absent. */
+    readonly body: string;
+}
+/**
+ * Parse leading YAML frontmatter from a markdown document.
+ *
+ * For callers that cannot await. A block the fast path refuses loads `yaml`
+ * synchronously; use {@link parseFrontmatterAsync} on paths where deferring the
+ * library to a dynamic import matters.
+ * @param source - full file contents.
+ * @returns the verbatim block, the parsed keys, and the remaining body.
+ */
+export declare function parseFrontmatter(source: string): Frontmatter;
+/**
+ * Parse leading YAML frontmatter, loading `yaml` with a dynamic import only
+ * when the fast path refuses the block.
+ * @param source - full file contents.
+ * @returns the verbatim block, the parsed keys, and the remaining body.
+ */
+export declare function parseFrontmatterAsync(source: string): Promise<Frontmatter>;