@abhishekmcp/notes 0.1.1 → 0.3.0

package/README.md

@@ -1,40 +1,82 @@
 # @abhishekmcp/notes
 
-An [MCP](https://modelcontextprotocol.io) server for managing local markdown notes. Lets any MCP client (Claude Desktop, Claude Code, Cursor, …) search, read, create, link, and organize notes in a folder on your machine.
+An [MCP](https://modelcontextprotocol.io) server for managing local markdown notes. Lets any MCP client (Claude Desktop, Claude Code, Cursor, …) search, link, and organize the notes in a folder on your machine — with ranked full-text search, tags, todos, and a wiki-link knowledge graph.
+
+Pure JavaScript, no native dependencies, no API keys — everything runs locally.
 
 ## Features
 
-**Tools**
-- `list_notes` — list all notes, newest first
-- `read_note` — read a note's contents
-- `create_note` — create a new note (optional overwrite)
-- `append_note` — append to a note (great for journals/logs)
+### Notes (token-efficient I/O)
+- `list_notes` — list notes (newest first) with pagination (`offset`/`limit`) and an optional `tag` filter
+- `read_note` — read a note; optionally just one heading's `section`, or a character window (`offset`/`limit`) with a truncation flag
+- `get_outline` — return only a note's heading tree (grasp a big note in a few tokens)
+- `create_note` — create a new note (optional `overwrite`)
+- `append_note` — append to a note, creating it if missing (great for journals/logs)
 - `delete_note` — delete a note
-- `search_notes` — full-text search across all notes
-- `get_backlinks` — find notes linking to a note via `[[wiki-link]]` syntax
-
-**Resources**
+- `move_note` — rename/move a note **and rewrite every `[[wiki-link]]`** across the vault that points at it
+
+### Search & discovery
+- `search_notes` — ranked full-text search ([MiniSearch](https://github.com/lucaong/minisearch)); supports `fuzzy` and `prefix` matching, a `field` filter (`title`/`tag`/`body`/`path`), and returns ranked snippets with surrounding context
+- `semantic_search` — **meaning-based** search using local embeddings; finds related notes even with no shared keywords (e.g. "puppy" matches a note about "canine companions"). Optional `hybrid` mode fuses semantic + keyword ranking
+- `list_tags` — every tag across the vault with note counts
+- `list_todos` — aggregate `- [ ]` / `- [x]` checkboxes across all notes
+
+### Knowledge graph
+- `get_backlinks` — notes linking to a note via `[[wiki-link]]` syntax
+- `get_neighbors` — notes within N hops over the (undirected) link graph (depth/limit capped)
+- `find_path` — shortest wiki-link chain between two notes
+- `related_notes` — notes ranked by shared links + shared tags
+- `graph_overview` — aggregate health: note/link/tag counts, top hubs, orphans, broken-link count
+- `broken_links` — wiki-links that point at notes which don't exist
+
+### Resources
 - Every note is exposed as a `notes://<name>` resource.
 
-All file access is sandboxed to the notes directory — paths that try to escape it are rejected.
+### Frontmatter & tags
+Notes may start with a YAML frontmatter block; `title` and `tags` (a list or comma-separated string) are recognized. Inline `#hashtags` in the body are also collected as tags.
 
-## Install & build
-
-```bash
-npm install
-npm run build
+```markdown
+---
+title: My Note
+tags: [project, ideas]
+---
+# My Note
+Links to [[another-note]]. Some inline #tag too.
 ```
 
 ## Configuration
 
-Set `NOTES_DIR` to choose where notes live (defaults to `~/notes`):
+All via environment variables:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `NOTES_DIR` | `~/notes` | Directory where notes live (a leading `~` is expanded). |
+| `NOTES_READONLY` | _unset_ | Set to `1` to disable all mutating tools (`create`/`append`/`delete`/`move` are not even registered) — safe for sharing a vault. |
+| `NOTES_NO_CACHE` | _unset_ | Set to `1` to skip the on-disk index cache and rebuild in memory each start. |
+| `NOTES_MODEL_DIR` | `~/.cache/mcp-notes/models` | Where the semantic-search embedding model is cached. |
+
+### Semantic search & the embedding model
+`semantic_search` runs the [all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2) model **locally** via WebAssembly ([onnxruntime-web](https://github.com/microsoft/onnxruntime)) — no API keys, no native dependencies, no data leaves your machine. The quantized model (~23 MB) is downloaded **once** on first use into `NOTES_MODEL_DIR` and cached; embeddings are stored in `<NOTES_DIR>/.notes-embeddings.json` and incrementally updated as notes change. The first `semantic_search` call needs network access for the download and embeds the whole vault; everything after that is offline and fast. Keyword search and all other tools work without ever triggering this.
+
+### Index cache
+For fast warm starts the server persists its search index to `<NOTES_DIR>/.notes-index.json` and, on startup, incrementally re-parses only the notes that changed (by mtime/size) since last run. The cache is rebuilt automatically if it's missing, unreadable, or from an older index version. Files on disk are always the source of truth.
+
+## Security
+
+All filesystem access is sandboxed to the notes directory:
+- Path traversal (`../`) and absolute paths are rejected.
+- Symlinks inside the vault that resolve outside it are rejected (realpath containment).
+- Single files above a size limit are refused (DoS / context guard).
+- Writes are atomic (temp file + rename), so a crash can't leave a torn note.
+
+## Usage
+
+### Claude Code
 
 ```bash
-export NOTES_DIR="$HOME/my-notes"
+claude mcp add notes --env NOTES_DIR=$HOME/notes -- npx -y @abhishekmcp/notes
 ```
 
-## Connecting to a client
-
 ### Claude Desktop
 
 Add to `claude_desktop_config.json`:
@@ -43,38 +85,27 @@ Add to `claude_desktop_config.json`:
 {
   "mcpServers": {
     "notes": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-suite/servers/notes/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@abhishekmcp/notes"],
       "env": { "NOTES_DIR": "/absolute/path/to/your/notes" }
     }
   }
 }
 ```
 
-### Claude Code
+To share a vault read-only, add `"NOTES_READONLY": "1"` to `env`.
+
+## Develop from source
 
 ```bash
-claude mcp add notes --env NOTES_DIR=$HOME/notes -- node /absolute/path/to/mcp-suite/servers/notes/dist/index.js
+npm install                      # from the repo root
+npm run build -w servers/notes
+node servers/notes/dist/index.js # NOTES_DIR=... to point at a vault
 ```
 
 ## Publishing to npm
 
-This package publishes automatically via GitHub Actions (Trusted Publishing / OIDC) when a
-release tagged `notes-v<version>` is created. See the repo root for the CD workflow.
-
-Once published, users can run it without cloning:
-
-```json
-{
-  "mcpServers": {
-    "notes": {
-      "command": "npx",
-      "args": ["-y", "@abhishekmcp/notes"],
-      "env": { "NOTES_DIR": "/path/to/notes" }
-    }
-  }
-}
-```
+Publishes automatically via GitHub Actions (Trusted Publishing / OIDC) when a release tagged `notes-v<version>` is created. See the repo root for the CD workflow.
 
 ## License
 

package/dist/config.d.ts

@@ -0,0 +1,41 @@
+/** Index cache format version — bump to force a full rebuild on upgrade. */
+export declare const INDEX_VERSION = 1;
+/** Cache file name kept inside the notes dir (excluded from notes). */
+export declare const INDEX_FILENAME = ".notes-index.json";
+/** Refuse to read/index any single note larger than this (DoS / context guard). */
+export declare const MAX_FILE_BYTES: number;
+/**
+ * Resolve the notes directory from NOTES_DIR, defaulting to ~/notes.
+ * A leading "~" is expanded to the home directory.
+ */
+export declare function getNotesDir(): string;
+/** Absolute path to the persisted index cache. */
+export declare function getIndexPath(): string;
+/** When true, all mutating tools are disabled (safe for sharing a vault read-only). */
+export declare function isReadOnly(): boolean;
+/** When true, skip the on-disk index cache and rebuild in memory each start. */
+export declare function cacheDisabled(): boolean;
+/** Embedding model identity (recorded in the cache to invalidate on change). */
+export declare const EMBED_MODEL_ID = "Xenova/all-MiniLM-L6-v2:quantized";
+/** Embedding dimensionality of all-MiniLM-L6-v2. */
+export declare const EMBED_DIM = 384;
+/** Max WordPiece tokens fed to the model (longer notes are truncated). */
+export declare const EMBED_MAX_TOKENS = 256;
+/** Bump to force re-embedding of every note on upgrade. */
+export declare const EMBED_CACHE_VERSION = 1;
+/** Sidecar cache of per-note vectors, kept inside the notes dir. */
+export declare const EMBEDDINGS_FILENAME = ".notes-embeddings.json";
+/** Quantized ONNX model (~23 MB) — downloaded once at runtime. */
+export declare const EMBED_MODEL_URL = "https://huggingface.co/Xenova/all-MiniLM-L6-v2/resolve/main/onnx/model_quantized.onnx";
+/** BERT-uncased vocabulary (~232 KB) for the hand-rolled tokenizer. */
+export declare const EMBED_VOCAB_URL = "https://huggingface.co/Xenova/all-MiniLM-L6-v2/resolve/main/vocab.txt";
+/** Local filenames for the cached artifacts. */
+export declare const EMBED_MODEL_FILE = "all-MiniLM-L6-v2.quantized.onnx";
+export declare const EMBED_VOCAB_FILE = "all-MiniLM-L6-v2.vocab.txt";
+/**
+ * Directory where the embedding model + vocab are cached (downloaded once per
+ * machine). Override with NOTES_MODEL_DIR; defaults to ~/.cache/mcp-notes/models.
+ */
+export declare function getModelDir(): string;
+/** Absolute path to the persisted embeddings cache (sidecar to the text index). */
+export declare function getEmbeddingsPath(): string;

package/dist/config.js

@@ -0,0 +1,67 @@
+import { homedir } from "node:os";
+import path from "node:path";
+/** Index cache format version — bump to force a full rebuild on upgrade. */
+export const INDEX_VERSION = 1;
+/** Cache file name kept inside the notes dir (excluded from notes). */
+export const INDEX_FILENAME = ".notes-index.json";
+/** Refuse to read/index any single note larger than this (DoS / context guard). */
+export const MAX_FILE_BYTES = 5 * 1024 * 1024; // 5 MB
+/**
+ * Resolve the notes directory from NOTES_DIR, defaulting to ~/notes.
+ * A leading "~" is expanded to the home directory.
+ */
+export function getNotesDir() {
+    const raw = process.env.NOTES_DIR ?? path.join(homedir(), "notes");
+    const expanded = raw.startsWith("~")
+        ? path.join(homedir(), raw.slice(1))
+        : raw;
+    return path.resolve(expanded);
+}
+/** Absolute path to the persisted index cache. */
+export function getIndexPath() {
+    return path.join(getNotesDir(), INDEX_FILENAME);
+}
+/** When true, all mutating tools are disabled (safe for sharing a vault read-only). */
+export function isReadOnly() {
+    return process.env.NOTES_READONLY === "1";
+}
+/** When true, skip the on-disk index cache and rebuild in memory each start. */
+export function cacheDisabled() {
+    return process.env.NOTES_NO_CACHE === "1";
+}
+// --- Semantic search (v0.3) ----------------------------------------------
+/** Embedding model identity (recorded in the cache to invalidate on change). */
+export const EMBED_MODEL_ID = "Xenova/all-MiniLM-L6-v2:quantized";
+/** Embedding dimensionality of all-MiniLM-L6-v2. */
+export const EMBED_DIM = 384;
+/** Max WordPiece tokens fed to the model (longer notes are truncated). */
+export const EMBED_MAX_TOKENS = 256;
+/** Bump to force re-embedding of every note on upgrade. */
+export const EMBED_CACHE_VERSION = 1;
+/** Sidecar cache of per-note vectors, kept inside the notes dir. */
+export const EMBEDDINGS_FILENAME = ".notes-embeddings.json";
+const HF_BASE = "https://huggingface.co/Xenova/all-MiniLM-L6-v2/resolve/main";
+/** Quantized ONNX model (~23 MB) — downloaded once at runtime. */
+export const EMBED_MODEL_URL = `${HF_BASE}/onnx/model_quantized.onnx`;
+/** BERT-uncased vocabulary (~232 KB) for the hand-rolled tokenizer. */
+export const EMBED_VOCAB_URL = `${HF_BASE}/vocab.txt`;
+/** Local filenames for the cached artifacts. */
+export const EMBED_MODEL_FILE = "all-MiniLM-L6-v2.quantized.onnx";
+export const EMBED_VOCAB_FILE = "all-MiniLM-L6-v2.vocab.txt";
+/**
+ * Directory where the embedding model + vocab are cached (downloaded once per
+ * machine). Override with NOTES_MODEL_DIR; defaults to ~/.cache/mcp-notes/models.
+ */
+export function getModelDir() {
+    const override = process.env.NOTES_MODEL_DIR;
+    if (override) {
+        const expanded = override.startsWith("~") ? path.join(homedir(), override.slice(1)) : override;
+        return path.resolve(expanded);
+    }
+    return path.join(homedir(), ".cache", "mcp-notes", "models");
+}
+/** Absolute path to the persisted embeddings cache (sidecar to the text index). */
+export function getEmbeddingsPath() {
+    return path.join(getNotesDir(), EMBEDDINGS_FILENAME);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAE/B,uEAAuE;AACvE,MAAM,CAAC,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAElD,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO;AAEtD;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QAClC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,GAAG,CAAC;IACR,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,YAAY;IAC1B,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,CAAC;AAClD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,GAAG,CAAC;AAC5C,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,GAAG,CAAC;AAC5C,CAAC;AAED,4EAA4E;AAE5E,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAG,mCAAmC,CAAC;AAClE,oDAAoD;AACpD,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,CAAC;AAC7B,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,oEAAoE;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAE5D,MAAM,OAAO,GAAG,6DAA6D,CAAC;AAC9E,kEAAkE;AAClE,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,OAAO,4BAA4B,CAAC;AACtE,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,OAAO,YAAY,CAAC;AACtD,gDAAgD;AAChD,MAAM,CAAC,MAAM,gBAAgB,GAAG,iCAAiC,CAAC;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAAG,4BAA4B,CAAC;AAE7D;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC7C,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,QAAQ,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC/F,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;AAC/D,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,iBAAiB;IAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,mBAAmB,CAAC,CAAC;AACvD,CAAC"}

package/dist/embed.d.ts

@@ -0,0 +1,9 @@
+/** Idempotent, concurrency-safe lazy initialization. */
+export declare function ensureModel(): Promise<void>;
+/** True once the model has been downloaded + loaded. */
+export declare function isReady(): boolean;
+/**
+ * Embed a single text into an L2-normalized 384-dim vector (cosine == dot
+ * product). Mean-pools the model's last_hidden_state over the attention mask.
+ */
+export declare function embed(text: string): Promise<Float32Array>;

package/dist/embed.js

@@ -0,0 +1,134 @@
+/**
+ * Lazy embedding engine: runs all-MiniLM-L6-v2 (ONNX) on onnxruntime-web (WASM,
+ * no native deps). The model + vocab are downloaded once to a persistent cache
+ * on first use; nothing here runs at server startup. `onnxruntime-web` is
+ * dynamically imported so a server that never does semantic search never loads
+ * the WASM runtime.
+ */
+import { promises as fs } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { EMBED_DIM, EMBED_MAX_TOKENS, EMBED_MODEL_FILE, EMBED_MODEL_URL, EMBED_VOCAB_FILE, EMBED_VOCAB_URL, getModelDir, } from "./config.js";
+import { WordPieceTokenizer } from "./tokenizer.js";
+let session = null;
+let tokenizer = null;
+let initPromise = null;
+/** Download a URL to `dest` atomically (temp + rename), retrying on 429/5xx. */
+async function download(url, dest) {
+    let lastErr;
+    for (let attempt = 0; attempt < 4; attempt++) {
+        try {
+            const res = await fetch(url);
+            if (res.status === 429 || res.status >= 500) {
+                throw new Error(`HTTP ${res.status} fetching ${url}`);
+            }
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status} fetching ${url}`);
+            const buf = Buffer.from(await res.arrayBuffer());
+            const tmp = `${dest}.${process.pid}.tmp`;
+            await fs.writeFile(tmp, buf);
+            await fs.rename(tmp, dest);
+            return;
+        }
+        catch (err) {
+            lastErr = err;
+            await new Promise((r) => setTimeout(r, 500 * 2 ** attempt)); // backoff
+        }
+    }
+    throw new Error(`Failed to download ${url}: ${lastErr?.message ?? lastErr}`);
+}
+/** Ensure a cached file exists, downloading it if missing. */
+async function ensureFile(url, dest) {
+    try {
+        await fs.access(dest);
+    }
+    catch {
+        await fs.mkdir(path.dirname(dest), { recursive: true });
+        await download(url, dest);
+    }
+}
+/** Download artifacts (once) and build the tokenizer + WASM inference session. */
+async function init() {
+    const dir = getModelDir();
+    const modelPath = path.join(dir, EMBED_MODEL_FILE);
+    const vocabPath = path.join(dir, EMBED_VOCAB_FILE);
+    await ensureFile(EMBED_VOCAB_URL, vocabPath);
+    await ensureFile(EMBED_MODEL_URL, modelPath);
+    tokenizer = new WordPieceTokenizer(await fs.readFile(vocabPath, "utf8"));
+    const ort = await import("onnxruntime-web");
+    ort.env.wasm.numThreads = 1; // single-thread: no SharedArrayBuffer / worker isolation needed
+    // Best-effort: point the WASM loader at the .wasm shipped in node_modules.
+    // (onnxruntime-web self-resolves from its own module URL when this isn't set.)
+    try {
+        const require = createRequire(import.meta.url);
+        ort.env.wasm.wasmPaths = path.dirname(require.resolve("onnxruntime-web")) + path.sep;
+    }
+    catch {
+        /* fall back to onnxruntime-web's own resolution */
+    }
+    const modelBytes = new Uint8Array(await fs.readFile(modelPath));
+    session = await ort.InferenceSession.create(modelBytes, { executionProviders: ["wasm"] });
+}
+/** Idempotent, concurrency-safe lazy initialization. */
+export async function ensureModel() {
+    if (session && tokenizer)
+        return;
+    if (!initPromise) {
+        initPromise = init().catch((err) => {
+            initPromise = null; // allow retry on a later call
+            throw err;
+        });
+    }
+    await initPromise;
+}
+/** True once the model has been downloaded + loaded. */
+export function isReady() {
+    return session !== null && tokenizer !== null;
+}
+/**
+ * Embed a single text into an L2-normalized 384-dim vector (cosine == dot
+ * product). Mean-pools the model's last_hidden_state over the attention mask.
+ */
+export async function embed(text) {
+    await ensureModel();
+    const ort = await import("onnxruntime-web");
+    const tok = tokenizer.encode(text, EMBED_MAX_TOKENS);
+    const seq = tok.inputIds.length;
+    const dims = [1, seq];
+    const feeds = {
+        input_ids: new ort.Tensor("int64", BigInt64Array.from(tok.inputIds, BigInt), dims),
+        attention_mask: new ort.Tensor("int64", BigInt64Array.from(tok.attentionMask, BigInt), dims),
+    };
+    // Some exports require token_type_ids (all-zero for a single segment).
+    if (session.inputNames.includes("token_type_ids")) {
+        feeds.token_type_ids = new ort.Tensor("int64", new BigInt64Array(seq), dims);
+    }
+    const results = await session.run(feeds);
+    const outName = session.outputNames.includes("last_hidden_state")
+        ? "last_hidden_state"
+        : session.outputNames[0];
+    const data = results[outName].data; // [1, seq, EMBED_DIM]
+    // Mean-pool over tokens weighted by the attention mask, then L2-normalize.
+    const out = new Float32Array(EMBED_DIM);
+    let maskSum = 0;
+    for (let t = 0; t < seq; t++) {
+        const m = tok.attentionMask[t];
+        if (!m)
+            continue;
+        maskSum += m;
+        const base = t * EMBED_DIM;
+        for (let d = 0; d < EMBED_DIM; d++)
+            out[d] += data[base + d] * m;
+    }
+    const denom = maskSum || 1;
+    let norm = 0;
+    for (let d = 0; d < EMBED_DIM; d++) {
+        out[d] /= denom;
+        norm += out[d] * out[d];
+    }
+    norm = Math.sqrt(norm) || 1;
+    for (let d = 0; d < EMBED_DIM; d++)
+        out[d] /= norm;
+    return out;
+}
+//# sourceMappingURL=embed.js.map

package/dist/embed.js.map

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

package/dist/fsutil.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Validate a user-supplied note name. Rejects control characters, absolute
+ * paths, and absurdly long names. Returns the name with a trailing ".md".
+ */
+export declare function validateName(name: string): string;
+/**
+ * Resolve a note name to a safe absolute path inside the notes dir, checking
+ * both lexical traversal (`../`) and symlink escapes. Async because the symlink
+ * check touches the filesystem.
+ */
+export declare function resolveSafe(name: string): Promise<string>;
+/** Read a note's raw text, guarding against oversized files. */
+export declare function readRaw(absPath: string): Promise<string>;
+/** Atomically write a file: write to a temp sibling, then rename into place. */
+export declare function atomicWrite(absPath: string, content: string): Promise<void>;
+export interface NoteFile {
+    name: string;
+    fullPath: string;
+    size: number;
+    mtimeMs: number;
+}
+/** Recursively list markdown note files, skipping dotfiles and the index cache. */
+export declare function listNoteFiles(): Promise<NoteFile[]>;

package/dist/fsutil.js

@@ -0,0 +1,113 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { getNotesDir, INDEX_FILENAME, MAX_FILE_BYTES } from "./config.js";
+/** Matches ASCII control characters (0x00–0x1f and DEL 0x7f). */
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+/**
+ * Validate a user-supplied note name. Rejects control characters, absolute
+ * paths, and absurdly long names. Returns the name with a trailing ".md".
+ */
+export function validateName(name) {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new Error("Note name must be a non-empty string.");
+    }
+    if (name.length > 512) {
+        throw new Error("Note name is too long (max 512 chars).");
+    }
+    if (CONTROL_CHARS.test(name)) {
+        throw new Error("Note name contains control characters.");
+    }
+    if (path.isAbsolute(name)) {
+        throw new Error("Note name must be relative, not an absolute path.");
+    }
+    return name.endsWith(".md") ? name : `${name}.md`;
+}
+/** Lexical containment check: does the resolved path stay inside the notes dir? */
+function lexicallyInside(dir, resolved) {
+    const rel = path.relative(dir, resolved);
+    return rel === "" ? false : !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/**
+ * Verify, following symlinks, that `absPath` resolves inside the notes dir.
+ * Walks up to the nearest existing ancestor (so it works for files that don't
+ * exist yet), realpaths it, then re-appends the non-existing suffix lexically.
+ * Defeats symlinks placed *inside* the notes dir that point outside it.
+ */
+async function realpathInside(absPath) {
+    const root = await fs.realpath(getNotesDir());
+    let cur = absPath;
+    // Walk up until we hit a path that exists on disk.
+    for (;;) {
+        try {
+            const realCur = await fs.realpath(cur);
+            const suffix = path.relative(cur, absPath); // "" when cur === absPath
+            const finalReal = suffix ? path.join(realCur, suffix) : realCur;
+            const rel = path.relative(root, finalReal);
+            return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return false; // reached filesystem root
+            cur = parent;
+        }
+    }
+}
+/**
+ * Resolve a note name to a safe absolute path inside the notes dir, checking
+ * both lexical traversal (`../`) and symlink escapes. Async because the symlink
+ * check touches the filesystem.
+ */
+export async function resolveSafe(name) {
+    const dir = getNotesDir();
+    const resolved = path.resolve(dir, validateName(name));
+    if (!lexicallyInside(dir, resolved)) {
+        throw new Error(`Refusing to access "${name}": path escapes the notes directory.`);
+    }
+    if (!(await realpathInside(resolved))) {
+        throw new Error(`Refusing to access "${name}": resolves (via symlink) outside the notes directory.`);
+    }
+    return resolved;
+}
+/** Read a note's raw text, guarding against oversized files. */
+export async function readRaw(absPath) {
+    const stat = await fs.stat(absPath);
+    if (stat.size > MAX_FILE_BYTES) {
+        throw new Error(`Note is too large to read (${stat.size} bytes > ${MAX_FILE_BYTES} limit).`);
+    }
+    return fs.readFile(absPath, "utf8");
+}
+/** Atomically write a file: write to a temp sibling, then rename into place. */
+export async function atomicWrite(absPath, content) {
+    await fs.mkdir(path.dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, content, "utf8");
+    await fs.rename(tmp, absPath);
+}
+/** Recursively list markdown note files, skipping dotfiles and the index cache. */
+export async function listNoteFiles() {
+    const dir = getNotesDir();
+    await fs.mkdir(dir, { recursive: true });
+    const out = [];
+    async function walk(current) {
+        const entries = await fs.readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") || entry.name === INDEX_FILENAME)
+                continue; // skip dotfiles/cache
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                const stat = await fs.stat(full);
+                const rel = path.relative(dir, full).replace(/\.md$/, "").split(path.sep).join("/");
+                out.push({ name: rel, fullPath: full, size: stat.size, mtimeMs: stat.mtimeMs });
+            }
+        }
+    }
+    await walk(dir);
+    return out;
+}
+//# sourceMappingURL=fsutil.js.map

package/dist/fsutil.js.map

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

package/dist/graph.d.ts

@@ -0,0 +1,38 @@
+export interface NodeRef {
+    name: string;
+    title: string;
+}
+/** Notes that link to `name` via [[wiki-link]]. */
+export declare function getBacklinks(name: string): NodeRef[];
+export interface Neighbor extends NodeRef {
+    distance: number;
+}
+/** BFS over the undirected link graph up to `depth`, capped at `limit` nodes. */
+export declare function getNeighbors(name: string, depth?: number, limit?: number): Neighbor[];
+/** Shortest wiki-link chain between two notes (BFS, undirected). Null if none. */
+export declare function findPath(a: string, b: string): NodeRef[] | null;
+export interface RelatedNote extends NodeRef {
+    score: number;
+    sharedLinks: number;
+    sharedTags: number;
+}
+/** Rank other notes by shared out-links + shared tags with `name`. */
+export declare function relatedNotes(name: string, limit?: number): RelatedNote[];
+export interface GraphOverview {
+    notes: number;
+    links: number;
+    tags: number;
+    brokenLinks: number;
+    orphans: NodeRef[];
+    hubs: Array<NodeRef & {
+        degree: number;
+    }>;
+}
+/** Aggregate graph health: counts, top hubs, orphans. */
+export declare function graphOverview(hubLimit?: number, orphanLimit?: number): GraphOverview;
+export interface BrokenLink {
+    from: string;
+    target: string;
+}
+/** Wiki-links that point at notes which don't exist. */
+export declare function brokenLinks(): BrokenLink[];