memhook 0.4.1 → 0.5.0

package/dist/src/presetsCmd.js

@@ -0,0 +1,94 @@
+/**
+ * `memhook presets list|detect` — discover the built-in per-host source presets
+ * so the user never has to know a preset's name or hand-write its paths.
+ *
+ *   list    Show every built-in preset (name, summary, the dirs/globs it points
+ *           at). Static — no disk access.
+ *   detect  Scan this project (cwd) + the home dir for the preset directories
+ *           that actually hold matching `.md` files, then print the YAML snippet
+ *           (`presets: [...]`) that enables the ones found.
+ *
+ * This is the I/O shell around the pure detector in `src/sources.ts`
+ * (`detectPresets`), the same functional-core / imperative-shell split as
+ * init.ts ↔ install.ts and skillsCmd.ts ↔ skills.ts. `presets` is NOT on the
+ * hook path, so it may exit non-zero on user error and use the TTY
+ * (docs/SPECIFICATION.md §9). The detector never throws (a missing/denied dir is
+ * recorded as absent), so detect/list always exit 0.
+ */
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { makeAnsi } from "./ansi.js";
+import { HOST_PRESETS, PRESET_NAMES, detectPresets } from "./sources.js";
+function makeIo(env, out) {
+    const ansi = makeAnsi({ isTTY: Boolean(process.stdout.isTTY), env });
+    return { out: out ?? ((s) => process.stdout.write(s + "\n")), ansi };
+}
+/** Display a source dir + glob with a portable separator (path.join, never "/"). */
+function dirGlob(dir, glob) {
+    return join(dir, glob);
+}
+export function runPresets(opts) {
+    const env = opts.env ?? process.env;
+    const cwd = opts.cwd ?? process.cwd();
+    const home = opts.home ?? homedir();
+    const readDir = opts.readDir ?? ((dir) => readdirSync(dir));
+    const io = makeIo(env, opts.out);
+    if (opts.subcommand === "list")
+        return runList(io, cwd, home);
+    return runDetect(io, cwd, home, readDir);
+}
+function runList(io, cwd, home) {
+    const { ansi } = io;
+    io.out(ansi.bold("memhook host presets") + ansi.dim(" — built-in source bundles (all experimental)\n"));
+    for (const name of PRESET_NAMES) {
+        const def = HOST_PRESETS[name];
+        if (!def)
+            continue;
+        io.out(`  ${ansi.cyan(name)} ${ansi.dim("(experimental)")}`);
+        io.out(`      ${ansi.dim(def.summary)}`);
+        for (const s of def.sources) {
+            const dir = join(s.base === "cwd" ? cwd : home, s.rel);
+            io.out(`      ${ansi.dim(dirGlob(dir, s.glob))}`);
+        }
+    }
+    io.out(ansi.dim("\nAll presets are doc-verified but not live-tested → experimental " +
+        "until an echo-test.\nEnable in ~/.config/memhook/config.yaml:  " +
+        "presets: [name, …]\nFind which apply here with `memhook presets detect`."));
+    return 0;
+}
+function runDetect(io, cwd, home, readDir) {
+    const { ansi } = io;
+    const detections = detectPresets(cwd, home, readDir);
+    const matched = detections.filter((d) => d.matched);
+    io.out(ansi.bold("memhook presets detect") +
+        ansi.dim(" — scan this project + home for known host memory\n"));
+    for (const d of detections) {
+        const total = fileCount(d);
+        if (d.matched) {
+            io.out(`  ${ansi.green("●")} ${ansi.cyan(d.name)} ${ansi.dim(`— ${total} file(s)`)}`);
+            for (const dir of d.dirs) {
+                if (dir.files.length === 0)
+                    continue;
+                io.out(`      ${ansi.dim(`${dirGlob(dir.dir, dir.glob)} (${dir.files.length})`)}`);
+            }
+        }
+        else {
+            io.out(`  ${ansi.dim("○")} ${ansi.dim(`${d.name} — no matching files`)}`);
+        }
+    }
+    if (matched.length === 0) {
+        io.out(ansi.dim("\nNo known host memory found under this project or home. Nothing to enable."));
+        return 0;
+    }
+    const names = matched.map((d) => d.name).join(", ");
+    io.out("\n" +
+        ansi.bold(`Found ${matched.length} host preset(s) with memory.`) +
+        ansi.dim(" Enable (experimental) by adding to\n~/.config/memhook/config.yaml:\n"));
+    io.out(`  ${ansi.cyan(`presets: [${names}]`)}`);
+    io.out(ansi.dim("\nThen run `memhook build-catalog` (or restart Claude Code) to catalog them."));
+    return 0;
+}
+function fileCount(d) {
+    return d.dirs.reduce((n, dir) => n + dir.files.length, 0);
+}

package/dist/src/router.d.ts

@@ -19,6 +19,7 @@
  * Never blocks Claude Code.
  */
 import { type MemhookConfig } from "./config.js";
+import type { HarnessAdapter } from "./adapters/types.js";
 export interface HookInput {
     prompt: string;
     cwd?: string;
@@ -36,7 +37,19 @@ export interface HookOutput {
      */
     systemMessage?: string;
 }
+/**
+ * Claude Code hook entry point. Unchanged signature and output shape — a thin
+ * wrapper that drives the harness-agnostic pipeline through the Claude Code
+ * adapter (src/adapters/claudeCode.ts). Byte-identical to the pre-adapter hook.
+ */
 export declare function route(stdinJson: string, env?: NodeJS.ProcessEnv): Promise<HookOutput>;
+/**
+ * Generic harness entry point: parse the host's stdin into `{prompt, cwd}` with
+ * the adapter, run the selection pipeline, then serialise the result into the
+ * host's stdout envelope with the same adapter. The pipeline (`selectMemory`) is
+ * identical for every host; only `parseInput` / `formatOutput` differ.
+ */
+export declare function runHarness<T>(adapter: HarnessAdapter<T>, stdinJson: string, env?: NodeJS.ProcessEnv): Promise<T>;
 /**
  * Proactive `/curate` nudge. Returns a one-line `systemMessage` when the memory
  * catalog has grown past a threshold and the cooldown has elapsed, else
@@ -51,3 +64,23 @@ export declare function route(stdinJson: string, env?: NodeJS.ProcessEnv): Promi
  * Exported for direct unit testing.
  */
 export declare function maybeCurateNudge(config: MemhookConfig, catalogContent: string, now: number): string | undefined;
+/**
+ * Proactive presets nudge. Returns a one-line `systemMessage` when a known
+ * host's memory directory exists in this project (or home) but no `presets:`
+ * entry routes it yet, else undefined. It makes `memhook presets detect` (the
+ * #42 discovery command) self-announcing instead of something the user must know
+ * to run.
+ *
+ * Opt-in is preserved: the nudge only *suggests* the explicit `presets:` config;
+ * it never auto-routes anything (every preset is experimental — see
+ * `docs/SPECIFICATION.md` §24). Local-only and fully wrapped so any failure
+ * yields no nudge (fail-soft is never affected). The cooldown stamp is keyed by
+ * cwd because the presets signal is per-project (unlike the catalog-size signal
+ * behind the `/curate` nudge), so one project firing must not silence another's.
+ * Cost: like the curate nudge, the stamp is written only on a fire, so until one
+ * fires the detection runs per prompt — a few `readdir`s on mostly-absent dirs,
+ * the same order of I/O `readSelected` already does.
+ *
+ * Exported for direct unit testing.
+ */
+export declare function maybePresetsNudge(config: MemhookConfig, cwd: string, home: string, now: number): string | undefined;

package/dist/src/router.js

@@ -20,37 +20,55 @@
  */
 import { existsSync, readFileSync, writeFileSync, openSync, fstatSync, closeSync, appendFileSync, mkdirSync, readdirSync, } from "node:fs";
 import { join, dirname, basename } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 import { LocalCache } from "./cache.js";
 import { loadConfig } from "./config.js";
 import { PreFilter } from "./preFilter.js";
 import { createProvider } from "./providers/factory.js";
+import { activeCustomSources, resolveSources, resolveActivePresetNames, detectPresets, } from "./sources.js";
+import { claudeCodeAdapter } from "./adapters/claudeCode.js";
 const SAFE_BASENAME_RE = /^[A-Za-z0-9._-]+\.md$/;
-const EMPTY = {
-    hookSpecificOutput: {
-        hookEventName: "UserPromptSubmit",
-        additionalContext: "",
-    },
-};
+/** The harness-agnostic empty outcome: inject nothing, no nudge (fail-soft). */
+const EMPTY_RESULT = { additionalContext: "" };
+/**
+ * Claude Code hook entry point. Unchanged signature and output shape — a thin
+ * wrapper that drives the harness-agnostic pipeline through the Claude Code
+ * adapter (src/adapters/claudeCode.ts). Byte-identical to the pre-adapter hook.
+ */
 export async function route(stdinJson, env = process.env) {
+    return runHarness(claudeCodeAdapter, stdinJson, env);
+}
+/**
+ * Generic harness entry point: parse the host's stdin into `{prompt, cwd}` with
+ * the adapter, run the selection pipeline, then serialise the result into the
+ * host's stdout envelope with the same adapter. The pipeline (`selectMemory`) is
+ * identical for every host; only `parseInput` / `formatOutput` differ.
+ */
+export async function runHarness(adapter, stdinJson, env = process.env) {
+    const result = await selectMemory(stdinJson, adapter.parseInput, env);
+    return adapter.formatOutput(result);
+}
+/**
+ * Harness-agnostic selection pipeline. Owns the config gate, prefilter, catalog
+ * + API-key checks, the local cache, the provider call, file injection, the
+ * JSONL log, and the `/curate` nudge. Every error path returns `EMPTY_RESULT`
+ * (fail-soft) — the hook never throws out of here.
+ */
+async function selectMemory(stdinJson, parseInput, env) {
     const config = loadConfig(env);
     ensureDirs(config);
     evictStale(config);
     if (!config.enabled)
-        return EMPTY;
-    let input;
-    try {
-        input = JSON.parse(stdinJson);
-    }
-    catch {
-        return EMPTY;
-    }
-    if (!input.prompt || typeof input.prompt !== "string")
-        return EMPTY;
+        return EMPTY_RESULT;
+    const input = parseInput(stdinJson);
+    if (!input || !input.prompt || typeof input.prompt !== "string")
+        return EMPTY_RESULT;
     const cwd = input.cwd ?? process.cwd();
     const preFilter = new PreFilter(config.preFilter.trivialWordsFile, config.preFilter.defaultWords);
     if (config.preFilter.enabled && preFilter.isTrivial(input.prompt)) {
         logEntry(config, baseLog(input.prompt, "pre_filter_skip"));
-        return EMPTY;
+        return EMPTY_RESULT;
     }
     // Read the catalog through a single fd: `fstat` gives the cache-key mtime and
     // we read the content from the same handle. Using one open fd — instead of
@@ -73,14 +91,14 @@ export async function route(stdinJson, env = process.env) {
     }
     catch {
         logEntry(config, baseLog(input.prompt, "no_catalog"));
-        return EMPTY;
+        return EMPTY_RESULT;
     }
     // Provider-aware key gate: local providers (Ollama) need no API key.
     const needsKey = config.provider.type !== "ollama";
     const apiKey = config.provider.apiKeyEnv ? env[config.provider.apiKeyEnv] : undefined;
     if (needsKey && !apiKey) {
         logEntry(config, baseLog(input.prompt, "no_api_key"));
-        return EMPTY;
+        return EMPTY_RESULT;
     }
     const cache = new LocalCache(config.cache.dir, config.cache.ttlMin, config.cache.evictionDays);
     const cacheKey = config.cache.enabled
@@ -120,7 +138,7 @@ export async function route(stdinJson, env = process.env) {
         }
         catch {
             logEntry(config, baseLog(input.prompt, "provider_init_failed"));
-            return EMPTY;
+            return EMPTY_RESULT;
         }
         let resp;
         try {
@@ -133,7 +151,7 @@ export async function route(stdinJson, env = process.env) {
         }
         catch {
             logEntry(config, baseLog(input.prompt, "api_no_response"));
-            return EMPTY;
+            return EMPTY_RESULT;
         }
         latencyMs = resp.latencyMs;
         usage = resp.usage;
@@ -146,7 +164,7 @@ export async function route(stdinJson, env = process.env) {
                 cacheCreate: usage.cacheCreateTokens,
                 cacheRead: usage.cacheReadTokens,
             });
-            return EMPTY;
+            return EMPTY_RESULT;
         }
         const extracted = extractJsonArray(resp.rawText);
         if (extracted === null) {
@@ -158,7 +176,7 @@ export async function route(stdinJson, env = process.env) {
                 cacheCreate: usage.cacheCreateTokens,
                 cacheRead: usage.cacheReadTokens,
             });
-            return EMPTY;
+            return EMPTY_RESULT;
         }
         selectedJson = JSON.stringify(extracted);
         if (config.cache.enabled && selectedJson !== "[]") {
@@ -192,19 +210,25 @@ export async function route(stdinJson, env = process.env) {
         additionalSizeTokensEst: Math.floor(additional.length / 4),
         status,
     });
-    const output = {
-        hookSpecificOutput: {
-            hookEventName: "UserPromptSubmit",
-            additionalContext: additional,
-        },
-    };
+    const result = { additionalContext: additional };
     // Proactive `/curate` nudge — best-effort, local-only, never affects the
     // additionalContext contract or fail-soft. `catalogContent` is already in hand
-    // (read above), so the catalog-size signal is free.
+    // (read above), so the catalog-size signal is free. The adapter serialises it
+    // into the host's notice channel (Claude Code: `systemMessage`); a host with
+    // no equivalent simply drops it.
     const nudge = maybeCurateNudge(config, catalogContent, Date.now());
-    if (nudge)
-        output.systemMessage = nudge;
-    return output;
+    if (nudge) {
+        result.systemMessage = nudge;
+    }
+    else {
+        // Only one notice channel (`systemMessage`) exists, so the presets nudge is
+        // a fallback: it fires only on a turn the curate nudge did not. Each has its
+        // own long cooldown, so the collision is rare and never produces two notices.
+        const pnudge = maybePresetsNudge(config, cwd, homedir(), Date.now());
+        if (pnudge)
+            result.systemMessage = pnudge;
+    }
+    return result;
 }
 function buildSystemPrompt(catalog) {
     return `Tu es un sélecteur de mémoire pour Claude Code. Tu identifies les feedbacks et règles pertinents pour le prompt utilisateur. Tu réponds UNIQUEMENT avec un JSON array de basenames .md, sans explication, sans markdown code fence.
@@ -271,11 +295,15 @@ function extractJsonArray(text) {
     return result;
 }
 function readSelected(basenames, cwd, config) {
-    // Build search dirs: ~/.claude/projects/*/memory + global rules + cwd rules.
+    // Build search dirs: ~/.claude/projects/*/memory + global rules + cwd rules +
+    // any user-declared custom sources (host-autoloaded ones only when resurfacing,
+    // mirroring the catalog so the router never finds what the catalog omitted).
     const projectDirs = listProjectsMemoryDirs(config.searchDirs[0]);
     const rulesDir = config.searchDirs[1];
     const cwdRulesDir = join(cwd, ".claude", "rules");
-    const dirs = [...projectDirs, rulesDir, cwdRulesDir].filter((d) => typeof d === "string" && d.length > 0);
+    const allSources = resolveSources(config.customSources, config.presets, cwd, homedir(), readdirSync);
+    const customDirs = activeCustomSources(allSources, config.resurfaceHostLoaded).map((s) => s.dir);
+    const dirs = [...projectDirs, rulesDir, cwdRulesDir, ...customDirs].filter((d) => typeof d === "string" && d.length > 0);
     let additional = "";
     let injected = 0;
     const seen = [];
@@ -382,6 +410,59 @@ export function maybeCurateNudge(config, catalogContent, now) {
         return undefined; // a nudge must never break fail-soft
     }
 }
+/**
+ * Proactive presets nudge. Returns a one-line `systemMessage` when a known
+ * host's memory directory exists in this project (or home) but no `presets:`
+ * entry routes it yet, else undefined. It makes `memhook presets detect` (the
+ * #42 discovery command) self-announcing instead of something the user must know
+ * to run.
+ *
+ * Opt-in is preserved: the nudge only *suggests* the explicit `presets:` config;
+ * it never auto-routes anything (every preset is experimental — see
+ * `docs/SPECIFICATION.md` §24). Local-only and fully wrapped so any failure
+ * yields no nudge (fail-soft is never affected). The cooldown stamp is keyed by
+ * cwd because the presets signal is per-project (unlike the catalog-size signal
+ * behind the `/curate` nudge), so one project firing must not silence another's.
+ * Cost: like the curate nudge, the stamp is written only on a fire, so until one
+ * fires the detection runs per prompt — a few `readdir`s on mostly-absent dirs,
+ * the same order of I/O `readSelected` already does.
+ *
+ * Exported for direct unit testing.
+ */
+export function maybePresetsNudge(config, cwd, home, now) {
+    try {
+        if (!config.presetsNudge.enabled)
+            return undefined;
+        // Per-project stamp: a global stamp would let the first project hit in a
+        // window silence every other project's (per-cwd) presets signal.
+        const cwdHash = createHash("sha256").update(cwd).digest("hex").slice(0, 12);
+        const stampFile = join(config.cache.dir, `.presets-nudge-${cwdHash}`);
+        const last = readNudgeStamp(stampFile);
+        if (last !== null && now - last < config.presetsNudge.cooldownDays * 86_400_000) {
+            return undefined;
+        }
+        // Suggest a preset only when it has memory on disk that is NOT already routed
+        // — neither by an effective preset name (named entries AND `presets: [auto]`
+        // expansion, so an `auto` user is never nudged) nor by a hand-written
+        // `customSources` dir pointing at the same place (`presets:` is sugar over
+        // `customSources`, D31/D32). `enabled` keys on the EXPANDED names (not the raw
+        // config) so it suppresses regardless of the `resurfaceHostLoaded` gate, which
+        // would otherwise drop a hostAutoLoaded preset's dirs from `routedDirs`.
+        const enabled = new Set(resolveActivePresetNames(config.presets, cwd, home, readdirSync));
+        const routedDirs = new Set(activeCustomSources(resolveSources(config.customSources, config.presets, cwd, home, readdirSync), config.resurfaceHostLoaded).map((s) => s.dir));
+        const found = detectPresets(cwd, home, readdirSync)
+            .filter((d) => d.matched && !enabled.has(d.name))
+            .filter((d) => d.dirs.some((dir) => dir.files.length > 0 && !routedDirs.has(dir.dir)))
+            .map((d) => d.name);
+        if (found.length === 0)
+            return undefined;
+        writeNudgeStamp(stampFile, now);
+        return `🔌 memhook: found ${found.join(", ")} memory not yet routed by memhook. Run \`memhook presets detect\` to enable it.`;
+    }
+    catch {
+        return undefined; // a nudge must never break fail-soft
+    }
+}
 /** Count top-level `*.md` memory files (excludes MEMORY.md and the journal/ subdir). */
 function countMemoryFiles(projectsRoot) {
     let total = 0;

package/dist/src/sources.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Custom memory sources — let memhook cable onto memory that already exists in a
+ * project, wherever it lives and however its files are named, instead of only
+ * the built-in `~/.claude` zones.
+ *
+ * A user declares extra sources in the YAML config (`customSources:`); each is a
+ * directory of `.md` files plus a filename glob, a scope, and whether the host
+ * already auto-loads them at launch. The router catalogs + injects from these
+ * exactly like the built-in zones. Everything here is pure (no I/O) and total
+ * (never throws): malformed entries are dropped, not fatal — the hook stays
+ * fail-soft.
+ */
+export type SourceScope = "memory" | "rules";
+/** A resolved, fully-typed custom source (every field present). */
+export interface CustomSource {
+    /** Absolute directory to scan (`~` already expanded). */
+    dir: string;
+    /** Basename glob (`*`, `?`); defaults to `*.md`. */
+    glob: string;
+    /** `memory` (default) or `rules` — drives the catalog section + display. */
+    scope: SourceScope;
+    /**
+     * Whether the host loads these files in full at launch. When true they are
+     * skipped unless `resurfaceHostLoaded` is on (same contract as the built-in
+     * `~/.claude/rules` zones — see `MemhookConfig.resurfaceHostLoaded`).
+     */
+    hostAutoLoaded: boolean;
+}
+/** Expand a leading `~` / `~/` against the given home directory. */
+export declare function expandHome(p: string, home: string): string;
+/**
+ * Compile a basename glob into an anchored RegExp. Only `*` (any run) and `?`
+ * (one char) are special; every other character is matched literally. Operates
+ * on basenames only — never a path separator.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+/**
+ * From a raw directory listing, the `.md` files matching `glob`, sorted. Pure
+ * and total. The `.md` gate is intentional and shared with the router's
+ * injection guard (`SAFE_BASENAME_RE`): only `.md` can ever be injected, so a
+ * glob like `*.txt` yields nothing. The catalog builder and preset detection
+ * both filter through this so they can never disagree on what a source matches.
+ */
+export declare function listMatchingMdFiles(entries: readonly string[], glob: string): string[];
+/**
+ * Resolve untrusted YAML `customSources` into typed `CustomSource[]`. Anything
+ * that isn't a usable entry (not an object, missing/blank `dir`) is dropped.
+ * Never throws.
+ */
+export declare function resolveCustomSources(raw: unknown, home: string): CustomSource[];
+/**
+ * The custom sources that should actually be catalogued + scanned: a
+ * host-autoloaded source is active only when re-surfacing is requested. Both the
+ * catalog builder and the router filter through this so they never disagree.
+ */
+export declare function activeCustomSources(sources: readonly CustomSource[], resurfaceHostLoaded: boolean): CustomSource[];
+interface PresetSourceDef {
+    /** Resolve `rel` against the project cwd or the home directory. */
+    readonly base: "cwd" | "home";
+    readonly rel: string;
+    readonly glob: string;
+    readonly scope: SourceScope;
+    readonly hostAutoLoaded: boolean;
+}
+export interface PresetDef {
+    /** Doc-verified, not live-tested → always experimental until an echo-test. */
+    readonly experimental: true;
+    readonly summary: string;
+    readonly sources: readonly PresetSourceDef[];
+}
+/** Built-in presets keyed by name. Atomic `.md` conventions only. */
+export declare const HOST_PRESETS: Record<string, PresetDef>;
+/** All known preset names. */
+export declare const PRESET_NAMES: string[];
+/**
+ * Special `presets:` token: instead of naming presets, the user opts in once and
+ * memhook routes every preset it detects on disk. Explicit opt-in (never the
+ * default), so the cardinal opt-in design (D31/D32) holds; the routed presets are
+ * still experimental (§24). See `resolveActivePresetNames`.
+ */
+export declare const PRESET_AUTO = "auto";
+export declare function isPresetName(name: string): boolean;
+/**
+ * Keep only valid preset entries from untrusted YAML: known names plus the
+ * special `auto` token. Never throws.
+ */
+export declare function resolvePresetNames(raw: unknown): string[];
+/**
+ * Expand preset names into concrete `CustomSource[]`, resolving each template's
+ * `cwd`/`home` base. Unknown names are skipped. Pure + total.
+ */
+export declare function expandPresets(names: readonly string[], cwd: string, home: string): CustomSource[];
+/**
+ * Resolve the effective preset names. Without the `auto` token, this is just the
+ * known names as given. With `auto` (explicit opt-in), it expands to every preset
+ * detected on disk (via `readDir`), unioned with any explicitly-named presets and
+ * de-duplicated. `readDir` is consulted ONLY when `auto` is present, so a config
+ * without `auto` pays zero detection I/O. Pure-of-I/O (the reader is a seam) and
+ * total (`detectPresets` swallows reader errors).
+ */
+export declare function resolveActivePresetNames(names: readonly string[], cwd: string, home: string, readDir: (dir: string) => string[]): string[];
+/**
+ * The full set of user-declared sources: explicit `customSources` plus the
+ * expanded built-in `presets` (with `auto` resolved to the detected presets via
+ * `readDir`). The single place catalog + router agree on what "the custom
+ * sources" are, so they never diverge — including how `auto` expands.
+ */
+export declare function resolveSources(customSources: readonly CustomSource[], presets: readonly string[], cwd: string, home: string, readDir: (dir: string) => string[]): CustomSource[];
+/** One resolved preset directory and what it matched. */
+export interface PresetDirMatch {
+    /** Absolute directory the preset points at (cwd/home already resolved). */
+    dir: string;
+    /** The basename glob applied to that directory. */
+    glob: string;
+    /** Matching `.md` basenames (sorted); empty if the dir is absent or has none. */
+    files: string[];
+    /** Whether the directory was readable at all (distinguishes empty from missing). */
+    exists: boolean;
+}
+/** Detection result for one built-in preset. */
+export interface PresetDetection {
+    name: string;
+    summary: string;
+    /** Mirrors `PresetDef.experimental` — every built-in preset is experimental. */
+    experimental: true;
+    /** True when at least one of the preset's directories matched ≥1 `.md` file. */
+    matched: boolean;
+    dirs: PresetDirMatch[];
+}
+/**
+ * Scan every built-in preset against the filesystem (via the injected `readDir`)
+ * and report which ones hold matching memory. Pure of real I/O (the reader is a
+ * seam) and total: a `readDir` that throws on a missing/denied directory is
+ * caught and recorded as `exists: false`, never propagated. Presets are returned
+ * in `PRESET_NAMES` order so the output is deterministic.
+ */
+export declare function detectPresets(cwd: string, home: string, readDir: (dir: string) => string[]): PresetDetection[];
+export {};