memhook 0.4.1 → 0.5.0

package/dist/src/sources.js

@@ -0,0 +1,251 @@
+/**
+ * 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.
+ */
+import { join } from "node:path";
+/** Expand a leading `~` / `~/` against the given home directory. */
+export function expandHome(p, home) {
+    if (p === "~")
+        return home;
+    if (p.startsWith("~/") || p.startsWith("~\\"))
+        return join(home, p.slice(2));
+    return p;
+}
+/**
+ * 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 function globToRegExp(glob) {
+    let body = "";
+    for (const ch of glob) {
+        if (ch === "*")
+            body += ".*";
+        else if (ch === "?")
+            body += ".";
+        else
+            body += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${body}$`);
+}
+/**
+ * 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 function listMatchingMdFiles(entries, glob) {
+    const re = globToRegExp(glob);
+    return entries.filter((e) => e.endsWith(".md") && re.test(e)).sort();
+}
+/**
+ * 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 function resolveCustomSources(raw, home) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        if (typeof e["dir"] !== "string" || e["dir"].trim() === "")
+            continue;
+        const glob = typeof e["glob"] === "string" && e["glob"].trim() !== "" ? e["glob"] : "*.md";
+        const scope = e["scope"] === "rules" ? "rules" : "memory";
+        out.push({
+            dir: expandHome(e["dir"], home),
+            glob,
+            scope,
+            hostAutoLoaded: e["hostAutoLoaded"] === true,
+        });
+    }
+    return out;
+}
+/**
+ * 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 function activeCustomSources(sources, resurfaceHostLoaded) {
+    return sources.filter((s) => !s.hostAutoLoaded || resurfaceHostLoaded);
+}
+/** Built-in presets keyed by name. Atomic `.md` conventions only. */
+export const HOST_PRESETS = {
+    cline: {
+        experimental: true,
+        summary: "Cline — .clinerules/ (project) + ~/Documents/Cline/Rules/ (global)",
+        sources: [
+            { base: "cwd", rel: ".clinerules", glob: "*.md", scope: "rules", hostAutoLoaded: true },
+            {
+                base: "home",
+                rel: join("Documents", "Cline", "Rules"),
+                glob: "*.md",
+                scope: "rules",
+                hostAutoLoaded: true,
+            },
+        ],
+    },
+    continue: {
+        experimental: true,
+        summary: "Continue.dev — .continue/rules/ (project + ~)",
+        sources: [
+            {
+                base: "cwd",
+                rel: join(".continue", "rules"),
+                glob: "*.md",
+                scope: "rules",
+                hostAutoLoaded: false,
+            },
+            {
+                base: "home",
+                rel: join(".continue", "rules"),
+                glob: "*.md",
+                scope: "rules",
+                hostAutoLoaded: false,
+            },
+        ],
+    },
+    copilot: {
+        experimental: true,
+        summary: "GitHub Copilot — .github/instructions/*.instructions.md (project)",
+        sources: [
+            {
+                base: "cwd",
+                rel: join(".github", "instructions"),
+                glob: "*.instructions.md",
+                scope: "rules",
+                hostAutoLoaded: false,
+            },
+        ],
+    },
+    windsurf: {
+        experimental: true,
+        summary: "Windsurf — .windsurf/rules/ (project)",
+        sources: [
+            {
+                base: "cwd",
+                rel: join(".windsurf", "rules"),
+                glob: "*.md",
+                scope: "rules",
+                hostAutoLoaded: false,
+            },
+        ],
+    },
+};
+/** All known preset names. */
+export const PRESET_NAMES = Object.keys(HOST_PRESETS);
+/**
+ * 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 const PRESET_AUTO = "auto";
+export function isPresetName(name) {
+    return Object.prototype.hasOwnProperty.call(HOST_PRESETS, name);
+}
+/**
+ * Keep only valid preset entries from untrusted YAML: known names plus the
+ * special `auto` token. Never throws.
+ */
+export function resolvePresetNames(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((x) => typeof x === "string" && (isPresetName(x) || x === PRESET_AUTO));
+}
+/**
+ * Expand preset names into concrete `CustomSource[]`, resolving each template's
+ * `cwd`/`home` base. Unknown names are skipped. Pure + total.
+ */
+export function expandPresets(names, cwd, home) {
+    const out = [];
+    for (const name of names) {
+        const def = HOST_PRESETS[name];
+        if (!def)
+            continue;
+        for (const s of def.sources) {
+            out.push({
+                dir: join(s.base === "cwd" ? cwd : home, s.rel),
+                glob: s.glob,
+                scope: s.scope,
+                hostAutoLoaded: s.hostAutoLoaded,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * 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 function resolveActivePresetNames(names, cwd, home, readDir) {
+    const known = names.filter(isPresetName); // drops `auto` + any unknown token
+    if (!names.includes(PRESET_AUTO))
+        return known;
+    const detected = detectPresets(cwd, home, readDir)
+        .filter((d) => d.matched)
+        .map((d) => d.name);
+    return [...new Set([...known, ...detected])];
+}
+/**
+ * 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 function resolveSources(customSources, presets, cwd, home, readDir) {
+    const names = resolveActivePresetNames(presets, cwd, home, readDir);
+    return [...customSources, ...expandPresets(names, cwd, home)];
+}
+/**
+ * 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 function detectPresets(cwd, home, readDir) {
+    const out = [];
+    for (const name of PRESET_NAMES) {
+        const def = HOST_PRESETS[name];
+        if (!def)
+            continue;
+        const dirs = [];
+        for (const s of def.sources) {
+            const dir = join(s.base === "cwd" ? cwd : home, s.rel);
+            let entries = null;
+            try {
+                entries = readDir(dir);
+            }
+            catch {
+                entries = null;
+            }
+            const files = entries === null ? [] : listMatchingMdFiles(entries, s.glob);
+            dirs.push({ dir, glob: s.glob, files, exists: entries !== null });
+        }
+        out.push({
+            name,
+            summary: def.summary,
+            experimental: def.experimental,
+            matched: dirs.some((d) => d.files.length > 0),
+            dirs,
+        });
+    }
+    return out;
+}

package/dist/src/version.d.ts

@@ -9,4 +9,4 @@
  * the literal in lockstep with `package.json` + `.release-please-manifest.json`.
  * Do not bump it by hand.
  */
-export declare const MEMHOOK_VERSION = "0.4.1";
+export declare const MEMHOOK_VERSION = "0.5.0";

package/dist/src/version.js

@@ -9,4 +9,4 @@
  * the literal in lockstep with `package.json` + `.release-please-manifest.json`.
  * Do not bump it by hand.
  */
-export const MEMHOOK_VERSION = "0.4.1"; // x-release-please-version
+export const MEMHOOK_VERSION = "0.5.0"; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memhook",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Semantic memory router for Claude Code — picks relevant feedbacks & rules per prompt via Haiku, injects them as additionalContext.",
   "type": "module",
   "license": "MIT",