@abhishekmcp/notes 0.1.0 → 0.2.0

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+/** 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;

package/dist/config.js

@@ -0,0 +1,32 @@
+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";
+}
+//# 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"}

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[];

package/dist/graph.js

@@ -0,0 +1,160 @@
+/**
+ * Knowledge-graph queries over the wiki-link + tag structure captured in the
+ * store's per-note metadata. Everything here is read-only and returns compact
+ * node references (name + title), never full note bodies, to stay token-cheap.
+ */
+import { normalizeLinkTarget } from "./parse.js";
+import { getAllMeta, getMeta, noteExists } from "./store.js";
+const ref = (name, meta) => ({ name, title: meta?.title ?? name });
+/** out: name -> existing targets it links to; in: name -> notes linking to it. */
+function adjacency() {
+    const out = new Map();
+    const inc = new Map();
+    const meta = getAllMeta();
+    for (const name of meta.keys()) {
+        out.set(name, new Set());
+        inc.set(name, new Set());
+    }
+    for (const [name, m] of meta) {
+        for (const link of m.outLinks) {
+            const target = normalizeLinkTarget(link);
+            if (!meta.has(target) || target === name)
+                continue; // skip broken + self
+            out.get(name).add(target);
+            inc.get(target).add(name);
+        }
+    }
+    return { out, inc };
+}
+/** Notes that link to `name` via [[wiki-link]]. */
+export function getBacklinks(name) {
+    const target = normalizeLinkTarget(name);
+    const out = [];
+    for (const [n, m] of getAllMeta()) {
+        if (n === target)
+            continue;
+        if (m.outLinks.some((l) => normalizeLinkTarget(l) === target))
+            out.push(ref(n, m));
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** BFS over the undirected link graph up to `depth`, capped at `limit` nodes. */
+export function getNeighbors(name, depth = 1, limit = 50) {
+    const start = normalizeLinkTarget(name);
+    if (!noteExists(start))
+        return [];
+    const { out, inc } = adjacency();
+    const seen = new Set([start]);
+    const result = [];
+    let frontier = [start];
+    for (let d = 1; d <= depth && frontier.length; d++) {
+        const next = [];
+        for (const node of frontier) {
+            const around = new Set([...(out.get(node) ?? []), ...(inc.get(node) ?? [])]);
+            for (const nb of around) {
+                if (seen.has(nb))
+                    continue;
+                seen.add(nb);
+                result.push({ ...ref(nb, getMeta(nb)), distance: d });
+                next.push(nb);
+                if (result.length >= limit)
+                    return result;
+            }
+        }
+        frontier = next;
+    }
+    return result;
+}
+/** Shortest wiki-link chain between two notes (BFS, undirected). Null if none. */
+export function findPath(a, b) {
+    const from = normalizeLinkTarget(a);
+    const to = normalizeLinkTarget(b);
+    if (!noteExists(from) || !noteExists(to))
+        return null;
+    if (from === to)
+        return [ref(from, getMeta(from))];
+    const { out, inc } = adjacency();
+    const prev = new Map();
+    const seen = new Set([from]);
+    const queue = [from];
+    while (queue.length) {
+        const node = queue.shift();
+        const around = new Set([...(out.get(node) ?? []), ...(inc.get(node) ?? [])]);
+        for (const nb of around) {
+            if (seen.has(nb))
+                continue;
+            seen.add(nb);
+            prev.set(nb, node);
+            if (nb === to) {
+                const chain = [to];
+                let cur = to;
+                while (cur !== from) {
+                    cur = prev.get(cur);
+                    chain.unshift(cur);
+                }
+                return chain.map((n) => ref(n, getMeta(n)));
+            }
+            queue.push(nb);
+        }
+    }
+    return null;
+}
+/** Rank other notes by shared out-links + shared tags with `name`. */
+export function relatedNotes(name, limit = 10) {
+    const target = normalizeLinkTarget(name);
+    const self = getMeta(target);
+    if (!self)
+        return [];
+    const myLinks = new Set(self.outLinks.map(normalizeLinkTarget));
+    const myTags = new Set(self.tags.map((t) => t.toLowerCase()));
+    const scored = [];
+    for (const [n, m] of getAllMeta()) {
+        if (n === target)
+            continue;
+        const sharedLinks = m.outLinks.filter((l) => myLinks.has(normalizeLinkTarget(l))).length;
+        const sharedTags = m.tags.filter((t) => myTags.has(t.toLowerCase())).length;
+        const score = sharedLinks + sharedTags;
+        if (score > 0)
+            scored.push({ ...ref(n, m), score, sharedLinks, sharedTags });
+    }
+    return scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
+}
+/** Aggregate graph health: counts, top hubs, orphans. */
+export function graphOverview(hubLimit = 10, orphanLimit = 25) {
+    const { out, inc } = adjacency();
+    const meta = getAllMeta();
+    let links = 0;
+    const tags = new Set();
+    const hubs = [];
+    const orphans = [];
+    for (const [name, m] of meta) {
+        for (const t of m.tags)
+            tags.add(t.toLowerCase());
+        const degree = (out.get(name)?.size ?? 0) + (inc.get(name)?.size ?? 0);
+        links += out.get(name)?.size ?? 0;
+        if (degree === 0)
+            orphans.push(ref(name, m));
+        hubs.push({ ...ref(name, m), degree });
+    }
+    return {
+        notes: meta.size,
+        links,
+        tags: tags.size,
+        brokenLinks: brokenLinks().length,
+        orphans: orphans.slice(0, orphanLimit),
+        hubs: hubs.filter((h) => h.degree > 0).sort((a, b) => b.degree - a.degree).slice(0, hubLimit),
+    };
+}
+/** Wiki-links that point at notes which don't exist. */
+export function brokenLinks() {
+    const out = [];
+    for (const [name, m] of getAllMeta()) {
+        for (const link of m.outLinks) {
+            const target = normalizeLinkTarget(link);
+            if (target && !noteExists(target))
+                out.push({ from: name, target });
+        }
+    }
+    return out.sort((a, b) => a.from.localeCompare(b.from) || a.target.localeCompare(b.target));
+}
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

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