@cad0p/napkin 0.8.1

package/dist/utils/config.js

@@ -0,0 +1,112 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const DEFAULT_CONFIG = {
+    overview: {
+        depth: 3,
+        keywords: 8,
+    },
+    search: {
+        limit: 30,
+        snippetLines: 0,
+    },
+    daily: {
+        folder: "daily",
+        format: "YYYY-MM-DD",
+    },
+    templates: {
+        folder: "Templates",
+    },
+    graph: {
+        renderer: "auto",
+    },
+};
+/**
+ * Load napkin config from config.json in the .napkin/ directory.
+ * Missing fields fall back to defaults.
+ */
+export function loadConfig(napkinDir) {
+    const configPath = path.join(napkinDir, "config.json");
+    if (!fs.existsSync(configPath))
+        return { ...DEFAULT_CONFIG };
+    try {
+        const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        return deepMerge(DEFAULT_CONFIG, raw);
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+/**
+ * Save napkin config to config.json in the .napkin/ directory and sync to .obsidian/.
+ * If obsidianDir is not provided, resolves it from config.vault or defaults to .napkin/.obsidian/.
+ */
+export function saveConfig(napkinDir, config, obsidianDir) {
+    const configPath = path.join(napkinDir, "config.json");
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    const resolvedObsidian = obsidianDir ||
+        (config.vault?.obsidian
+            ? path.resolve(napkinDir, config.vault.obsidian)
+            : path.join(napkinDir, ".obsidian"));
+    syncObsidianConfig(resolvedObsidian, config);
+}
+/**
+ * Update specific config fields, save, and sync.
+ */
+export function updateConfig(napkinDir, partial) {
+    const current = loadConfig(napkinDir);
+    const updated = deepMerge(current, partial);
+    saveConfig(napkinDir, updated);
+    return updated;
+}
+/**
+ * Write .obsidian/ config files derived from napkin config.
+ * napkin is the source of truth — Obsidian reads from these.
+ */
+function syncObsidianConfig(obsidianDir, config) {
+    if (!fs.existsSync(obsidianDir)) {
+        fs.mkdirSync(obsidianDir, { recursive: true });
+    }
+    // daily-notes.json
+    fs.writeFileSync(path.join(obsidianDir, "daily-notes.json"), JSON.stringify({
+        folder: config.daily.folder,
+        format: config.daily.format,
+        template: `${config.templates.folder}/Daily Note`,
+    }, null, 2));
+    // templates.json
+    fs.writeFileSync(path.join(obsidianDir, "templates.json"), JSON.stringify({
+        folder: config.templates.folder,
+    }, null, 2));
+    // app.json
+    const appPath = path.join(obsidianDir, "app.json");
+    let app = {};
+    if (fs.existsSync(appPath)) {
+        try {
+            app = JSON.parse(fs.readFileSync(appPath, "utf-8"));
+        }
+        catch {
+            // ignore
+        }
+    }
+    app.alwaysUpdateLinks = true;
+    fs.writeFileSync(appPath, JSON.stringify(app, null, 2));
+}
+// biome-ignore lint/suspicious/noExplicitAny: deep merge requires flexible types
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const srcVal = source[key];
+        const tgtVal = target[key];
+        if (srcVal &&
+            typeof srcVal === "object" &&
+            !Array.isArray(srcVal) &&
+            tgtVal &&
+            typeof tgtVal === "object" &&
+            !Array.isArray(tgtVal)) {
+            result[key] = deepMerge(tgtVal, srcVal);
+        }
+        else {
+            result[key] = srcVal;
+        }
+    }
+    return result;
+}

package/dist/utils/exit-codes.d.ts

@@ -0,0 +1,5 @@
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_USER_ERROR = 2;
+export declare const EXIT_NOT_FOUND = 3;
+export declare const EXIT_NO_VAULT = 4;

package/dist/utils/exit-codes.js

@@ -0,0 +1,5 @@
+export const EXIT_SUCCESS = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_USER_ERROR = 2;
+export const EXIT_NOT_FOUND = 3;
+export const EXIT_NO_VAULT = 4;

package/dist/utils/files.d.ts

@@ -0,0 +1,135 @@
+import * as fs from "node:fs";
+export interface FileInfo {
+    path: string;
+    name: string;
+    extension: string;
+    size: number;
+    created: number;
+    modified: number;
+}
+export interface ListFilesOptions {
+    folder?: string;
+    ext?: string;
+}
+/**
+ * Directory names that walkers skip unconditionally (internal Obsidian/napkin
+ * state, VCS metadata, and package managers).
+ *
+ * Shared by listFiles, listFolders, walkMd (graph), and getVaultSize so all
+ * four walkers agree on what to exclude. This matters especially when a vault
+ * contains symlinks into external trees (e.g. Brazil workspace packages) whose
+ * node_modules/ would otherwise balloon results.
+ */
+export declare const SKIP_DIRS: ReadonlySet<string>;
+/** What a Dirent resolves to, following symlinks to their target. */
+export type EntryKind = "dir" | "file" | null;
+/**
+ * Classify a Dirent. For symlinks, follows to the target and reports the
+ * target kind. Returns null for broken symlinks, unreadable targets, and
+ * non-regular entries (sockets, FIFOs, devices).
+ *
+ * Using this lets walkers treat symlinks to directories/files as first-class
+ * entries while still gracefully skipping unreadable targets.
+ */
+export declare function direntKind(fullPath: string, entry: fs.Dirent): EntryKind;
+/**
+ * Resolve a directory's real path for cycle detection. Returns null on
+ * failure (permission errors, broken intermediate path, etc.) so callers
+ * can fail closed rather than risk an unbounded walk.
+ */
+export declare function safeRealpath(dir: string): string | null;
+/**
+ * Options for {@link walkDir}.
+ */
+export interface WalkDirOptions {
+    /**
+     * Called once per visited file or directory entry (after skip-dir
+     * filtering and symlink resolution). Never invoked with kind=null;
+     * non-regular and broken entries are filtered out by the walker.
+     */
+    onEntry: (fullPath: string, entry: fs.Dirent, kind: "dir" | "file") => void;
+    /**
+     * Optional predicate to prune directories. Called for each directory
+     * entry (including symlinked dirs) AFTER the SKIP_DIRS check. Return
+     * false to skip the directory entirely: it is neither reported via
+     * onEntry nor walked. Not consulted for files.
+     *
+     * Use this to apply stricter pruning than SKIP_DIRS (e.g. walkMd and
+     * listFolders prune all dot-prefixed directories).
+     */
+    shouldEnter?: (fullPath: string, entry: fs.Dirent) => boolean;
+}
+/**
+ * Walk a directory tree, invoking onEntry for each file and directory.
+ *
+ * Skip semantics:
+ * - Directory names in SKIP_DIRS are never entered or reported.
+ * - If shouldEnter is provided, directories for which it returns false
+ *   are also neither entered nor reported. This lets callers prune
+ *   subtrees (e.g. dotdirs) symmetrically with SKIP_DIRS — filtering
+ *   inside onEntry would only hide the report while still walking the
+ *   subtree.
+ *
+ * Symlink semantics:
+ * - Symlinks to regular files/directories are classified via direntKind
+ *   and reported with kind "dir" or "file".
+ * - A symlink that resolves to a directory is walked recursively.
+ * - Broken symlinks, sockets, FIFOs, and devices are silently skipped.
+ *
+ * Cycle detection: uses an on-stack set of realpaths for the current
+ * recursion path. A symlink that resolves to an ancestor in the descent
+ * is skipped exactly once; two sibling symlinks to the same target are
+ * both walked. realpathSync is only invoked when crossing a symlink
+ * boundary (or at the root), so symlink-free vaults pay no extra cost
+ * versus the pre-fix baseline.
+ *
+ * Fail-closed: if realpathSync fails on a subtree entered via a symlink,
+ * that subtree is skipped to avoid potential unbounded recursion.
+ */
+export declare function walkDir(root: string, opts: WalkDirOptions): void;
+/**
+ * Recursively list files in a vault.
+ *
+ * - Skips the directories in SKIP_DIRS (".obsidian", ".git", etc.).
+ * - Follows symlinks to files and directories. Note that symlinked content
+ *   may physically live outside vaultPath; callers that feed results to
+ *   downstream consumers (e.g. LLM prompts via the SDK) should be aware
+ *   that `readFile` of a returned path may access external data.
+ * - Detects symlink cycles via realpath tracking on the current recursion
+ *   path, so a symlink pointing back to an ancestor is entered at most
+ *   once. Sibling symlinks to the same target are both walked (each
+ *   contributes its own prefixed entries).
+ * - Broken symlinks, sockets, FIFOs, and unreadable entries are silently
+ *   skipped.
+ */
+export declare function listFiles(vaultPath: string, opts?: ListFilesOptions): string[];
+/**
+ * List folders in a vault. Same symlink semantics as listFiles.
+ */
+export declare function listFolders(vaultPath: string, parentFolder?: string): string[];
+/**
+ * Resolve a file reference (wikilink-style name or exact path) to a relative path in the vault.
+ * Throws on ambiguous matches so the user can disambiguate.
+ */
+export declare function resolveFile(vaultPath: string, fileRef: string): string | null;
+/**
+ * Like resolveFile but never throws on ambiguous matches.
+ * Returns the shallowest match (fewest path segments), matching Obsidian's behavior.
+ */
+export declare function resolveFileLoose(vaultPath: string, fileRef: string): string | null;
+/**
+ * Suggest similar filenames when a file isn't found.
+ * Returns up to 3 suggestions sorted by similarity.
+ */
+export declare function suggestFile(vaultPath: string, fileRef: string): string[];
+/**
+ * Read a file's contents, resolving by name or path.
+ */
+export declare function readFile(vaultPath: string, fileRef: string): {
+    path: string;
+    content: string;
+};
+/**
+ * Get file info for a resolved file path.
+ */
+export declare function getFileInfo(vaultPath: string, relativePath: string): FileInfo;

package/dist/utils/files.js

@@ -0,0 +1,299 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Directory names that walkers skip unconditionally (internal Obsidian/napkin
+ * state, VCS metadata, and package managers).
+ *
+ * Shared by listFiles, listFolders, walkMd (graph), and getVaultSize so all
+ * four walkers agree on what to exclude. This matters especially when a vault
+ * contains symlinks into external trees (e.g. Brazil workspace packages) whose
+ * node_modules/ would otherwise balloon results.
+ */
+export const SKIP_DIRS = new Set([
+    ".obsidian",
+    ".git",
+    ".trash",
+    ".nanny",
+    ".napkin",
+    "node_modules",
+]);
+/**
+ * Classify a Dirent. For symlinks, follows to the target and reports the
+ * target kind. Returns null for broken symlinks, unreadable targets, and
+ * non-regular entries (sockets, FIFOs, devices).
+ *
+ * Using this lets walkers treat symlinks to directories/files as first-class
+ * entries while still gracefully skipping unreadable targets.
+ */
+export function direntKind(fullPath, entry) {
+    if (entry.isDirectory())
+        return "dir";
+    if (entry.isFile())
+        return "file";
+    if (entry.isSymbolicLink()) {
+        try {
+            const stat = fs.statSync(fullPath); // follows symlinks
+            if (stat.isDirectory())
+                return "dir";
+            if (stat.isFile())
+                return "file";
+            return null; // socket / FIFO / device
+        }
+        catch {
+            // Broken symlink or target inaccessible.
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a directory's real path for cycle detection. Returns null on
+ * failure (permission errors, broken intermediate path, etc.) so callers
+ * can fail closed rather than risk an unbounded walk.
+ */
+export function safeRealpath(dir) {
+    try {
+        return fs.realpathSync(dir);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Walk a directory tree, invoking onEntry for each file and directory.
+ *
+ * Skip semantics:
+ * - Directory names in SKIP_DIRS are never entered or reported.
+ * - If shouldEnter is provided, directories for which it returns false
+ *   are also neither entered nor reported. This lets callers prune
+ *   subtrees (e.g. dotdirs) symmetrically with SKIP_DIRS — filtering
+ *   inside onEntry would only hide the report while still walking the
+ *   subtree.
+ *
+ * Symlink semantics:
+ * - Symlinks to regular files/directories are classified via direntKind
+ *   and reported with kind "dir" or "file".
+ * - A symlink that resolves to a directory is walked recursively.
+ * - Broken symlinks, sockets, FIFOs, and devices are silently skipped.
+ *
+ * Cycle detection: uses an on-stack set of realpaths for the current
+ * recursion path. A symlink that resolves to an ancestor in the descent
+ * is skipped exactly once; two sibling symlinks to the same target are
+ * both walked. realpathSync is only invoked when crossing a symlink
+ * boundary (or at the root), so symlink-free vaults pay no extra cost
+ * versus the pre-fix baseline.
+ *
+ * Fail-closed: if realpathSync fails on a subtree entered via a symlink,
+ * that subtree is skipped to avoid potential unbounded recursion.
+ */
+export function walkDir(root, opts) {
+    const onStack = new Set();
+    // Seed with the root's real path so a symlink back to the root is
+    // detected even though we don't mark the top-level descent as
+    // "via symlink".
+    const rootReal = safeRealpath(root);
+    if (rootReal !== null)
+        onStack.add(rootReal);
+    function walk(dir, viaSymlink) {
+        let stackKey = null;
+        if (viaSymlink) {
+            stackKey = safeRealpath(dir);
+            if (stackKey === null)
+                return; // inaccessible symlinked subtree
+            if (onStack.has(stackKey))
+                return; // cycle
+            onStack.add(stackKey);
+        }
+        try {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                const fullPath = path.join(dir, entry.name);
+                const kind = direntKind(fullPath, entry);
+                if (kind === null)
+                    continue;
+                if (kind === "dir") {
+                    // Check shouldEnter BEFORE reporting so that a pruned
+                    // directory is neither emitted nor walked, matching the
+                    // pre-consolidation semantics of listFolders/walkMd.
+                    if (opts.shouldEnter && !opts.shouldEnter(fullPath, entry))
+                        continue;
+                    opts.onEntry(fullPath, entry, kind);
+                    walk(fullPath, viaSymlink || entry.isSymbolicLink());
+                }
+                else {
+                    opts.onEntry(fullPath, entry, kind);
+                }
+            }
+        }
+        finally {
+            if (stackKey !== null)
+                onStack.delete(stackKey);
+        }
+    }
+    walk(root, false);
+}
+/**
+ * Recursively list files in a vault.
+ *
+ * - Skips the directories in SKIP_DIRS (".obsidian", ".git", etc.).
+ * - Follows symlinks to files and directories. Note that symlinked content
+ *   may physically live outside vaultPath; callers that feed results to
+ *   downstream consumers (e.g. LLM prompts via the SDK) should be aware
+ *   that `readFile` of a returned path may access external data.
+ * - Detects symlink cycles via realpath tracking on the current recursion
+ *   path, so a symlink pointing back to an ancestor is entered at most
+ *   once. Sibling symlinks to the same target are both walked (each
+ *   contributes its own prefixed entries).
+ * - Broken symlinks, sockets, FIFOs, and unreadable entries are silently
+ *   skipped.
+ */
+export function listFiles(vaultPath, opts) {
+    const results = [];
+    // Internal napkin files that shouldn't appear in vault content listings
+    const skipFiles = new Set(["config.json", "search-cache.json"]);
+    const baseDir = opts?.folder ? path.join(vaultPath, opts.folder) : vaultPath;
+    if (!fs.existsSync(baseDir))
+        return results;
+    walkDir(baseDir, {
+        onEntry: (fullPath, _entry, kind) => {
+            if (kind !== "file")
+                return;
+            // Skip internal config files at vault root
+            if (path.dirname(fullPath) === vaultPath &&
+                skipFiles.has(path.basename(fullPath)))
+                return;
+            const rel = path.relative(vaultPath, fullPath);
+            if (opts?.ext) {
+                if (path.extname(fullPath).slice(1) === opts.ext) {
+                    results.push(rel);
+                }
+            }
+            else {
+                results.push(rel);
+            }
+        },
+    });
+    return results.sort();
+}
+/**
+ * List folders in a vault. Same symlink semantics as listFiles.
+ */
+export function listFolders(vaultPath, parentFolder) {
+    const results = [];
+    const baseDir = parentFolder ? path.join(vaultPath, parentFolder) : vaultPath;
+    if (!fs.existsSync(baseDir))
+        return results;
+    walkDir(baseDir, {
+        onEntry: (fullPath, _entry, kind) => {
+            if (kind !== "dir")
+                return;
+            results.push(path.relative(vaultPath, fullPath));
+        },
+        // Prune dotdirs at descent time so their subtree is not walked
+        // (matches pre-consolidation listFolders behavior). walkDir already
+        // filters SKIP_DIRS; this is the additional dotdir policy.
+        shouldEnter: (_fullPath, entry) => !entry.name.startsWith("."),
+    });
+    return results.sort();
+}
+/**
+ * Find all .md files matching a wikilink-style name or exact path.
+ */
+function findMatches(vaultPath, fileRef) {
+    // Exact path
+    if (fileRef.includes("/") || fileRef.endsWith(".md")) {
+        const ref = fileRef.endsWith(".md") ? fileRef : `${fileRef}.md`;
+        const fullPath = path.join(vaultPath, ref);
+        return fs.existsSync(fullPath) ? [ref] : [];
+    }
+    // Wikilink-style: search by basename
+    const target = fileRef.toLowerCase();
+    const allFiles = listFiles(vaultPath, { ext: "md" });
+    return allFiles.filter((file) => path.basename(file, ".md").toLowerCase() === target);
+}
+/**
+ * Resolve a file reference (wikilink-style name or exact path) to a relative path in the vault.
+ * Throws on ambiguous matches so the user can disambiguate.
+ */
+export function resolveFile(vaultPath, fileRef) {
+    const matches = findMatches(vaultPath, fileRef);
+    if (matches.length > 1) {
+        throw new Error(`Ambiguous file reference "${fileRef}" matches ${matches.length} files: ${matches.join(", ")}. Use the full path to disambiguate.`);
+    }
+    return matches[0] ?? null;
+}
+/**
+ * Like resolveFile but never throws on ambiguous matches.
+ * Returns the shallowest match (fewest path segments), matching Obsidian's behavior.
+ */
+export function resolveFileLoose(vaultPath, fileRef) {
+    const matches = findMatches(vaultPath, fileRef);
+    if (matches.length > 1) {
+        matches.sort((a, b) => a.split("/").length - b.split("/").length);
+    }
+    return matches[0] ?? null;
+}
+/**
+ * Suggest similar filenames when a file isn't found.
+ * Returns up to 3 suggestions sorted by similarity.
+ */
+export function suggestFile(vaultPath, fileRef) {
+    const target = fileRef.toLowerCase();
+    const allFiles = listFiles(vaultPath, { ext: "md" });
+    const scored = allFiles
+        .map((f) => {
+        const basename = path.basename(f, ".md").toLowerCase();
+        // Simple substring match scoring
+        let score = 0;
+        if (basename.includes(target) || target.includes(basename))
+            score += 3;
+        // Shared prefix
+        let prefix = 0;
+        while (prefix < basename.length &&
+            prefix < target.length &&
+            basename[prefix] === target[prefix])
+            prefix++;
+        score += prefix;
+        return { file: f, score };
+    })
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 3);
+    return scored.map((s) => s.file);
+}
+/**
+ * Read a file's contents, resolving by name or path.
+ */
+export function readFile(vaultPath, fileRef) {
+    const resolved = resolveFile(vaultPath, fileRef);
+    if (!resolved) {
+        throw new Error(`File not found: ${fileRef}`);
+    }
+    const fullPath = path.join(vaultPath, resolved);
+    const content = fs.readFileSync(fullPath, "utf-8");
+    return { path: resolved, content };
+}
+/**
+ * Get file info for a resolved file path.
+ */
+export function getFileInfo(vaultPath, relativePath) {
+    const fullPath = path.join(vaultPath, relativePath);
+    const stat = fs.statSync(fullPath);
+    const ext = path.extname(relativePath);
+    return {
+        path: relativePath,
+        name: path.basename(relativePath, ext),
+        extension: ext.slice(1),
+        size: stat.size,
+        created: stat.birthtimeMs,
+        modified: stat.mtimeMs,
+    };
+}

package/dist/utils/formula.d.ts

@@ -0,0 +1,28 @@
+import Jexl from "jexl";
+/**
+ * Transform Obsidian expression syntax to jexl syntax.
+ * Converts .method(args) to |method(args) for known transforms.
+ * Also remaps if() to _if() since if is reserved.
+ */
+export declare function obsidianToJexl(expr: string): string;
+/**
+ * Create a configured jexl instance with all Obsidian Bases functions.
+ */
+export declare function createFormulaEngine(): InstanceType<typeof Jexl.Jexl>;
+/**
+ * Build a context object for formula evaluation from a database row.
+ */
+export declare function buildFormulaContext(columns: string[], row: unknown[], formulaResults?: Record<string, unknown>, thisFile?: {
+    name: string;
+    path: string;
+    folder: string;
+}): Record<string, unknown>;
+/**
+ * Evaluate all formulas for a single row.
+ * Handles formula dependencies (formula referencing another formula).
+ */
+export declare function evaluateFormulas(engine: InstanceType<typeof Jexl.Jexl>, formulas: Record<string, string>, columns: string[], row: unknown[], thisFile?: {
+    name: string;
+    path: string;
+    folder: string;
+}): Promise<Record<string, unknown>>;