@cad0p/napkin 0.8.1

package/dist/utils/output.js

@@ -0,0 +1,48 @@
+import chalk from "chalk";
+export const success = (msg) => console.log(chalk.green("✓"), msg);
+export const info = (msg) => console.log(chalk.blue("ℹ"), msg);
+export const warn = (msg) => console.log(chalk.yellow("⚠"), msg);
+export const error = (msg) => console.error(chalk.red("✗"), msg);
+export const errorWithHint = (msg, hint) => {
+    console.error(chalk.red("✗"), msg);
+    console.error(chalk.dim(`  ${hint}`));
+};
+/**
+ * Standard "file not found" error with suggestions.
+ * Import suggestFile where needed and pass results here.
+ */
+export function fileNotFound(ref, suggestions) {
+    error(`File not found: ${ref}`);
+    if (suggestions && suggestions.length > 0) {
+        console.error(chalk.dim(`  Did you mean: ${suggestions.join(", ")}?`));
+    }
+    else {
+        console.error(chalk.dim("  Run napkin file list to see all files."));
+    }
+}
+export const bold = (s) => chalk.bold(s);
+export const dim = (s) => chalk.dim(s);
+export const cmd = (s) => chalk.cyan(s);
+export const bullet = (msg) => console.log(chalk.green("●"), msg);
+export const bulletDim = (msg) => console.log(chalk.dim("●"), msg);
+export const hint = (msg) => console.log(chalk.dim(`  ${msg}`));
+export const nextStep = (command) => console.log(`  ${cmd(command)}`);
+export const header = (title) => {
+    console.log();
+    console.log(chalk.bold(title));
+    console.log();
+};
+export function jsonOutput(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+export function output(options, handlers) {
+    if (options.json && handlers.json) {
+        jsonOutput(handlers.json());
+    }
+    else if (options.quiet && handlers.quiet) {
+        handlers.quiet();
+    }
+    else {
+        handlers.human();
+    }
+}

package/dist/utils/search-cache.d.ts

@@ -0,0 +1,29 @@
+export interface CachedDoc {
+    id: number;
+    file: string;
+    basename: string;
+    mtime: number;
+}
+export interface SearchCacheData {
+    fingerprint: string;
+    /** JSON-serialized MiniSearch index */
+    index: string;
+    /** Doc metadata (without content — content is re-read for snippets) */
+    docs: CachedDoc[];
+    /** file -> inbound link count */
+    backlinkCounts: Record<string, number>;
+}
+/**
+ * Compute a fingerprint of all .md files in the vault based on paths and mtimes.
+ * Changes when files are added, removed, or modified.
+ */
+export declare function computeFingerprint(contentPath: string, folder?: string): string;
+/**
+ * Load cached search index if the fingerprint matches.
+ * Returns null if no cache, fingerprint mismatch, or corrupted data.
+ */
+export declare function loadSearchCache(configPath: string, currentFingerprint: string): SearchCacheData | null;
+/**
+ * Save search index cache to disk.
+ */
+export declare function saveSearchCache(configPath: string, data: SearchCacheData): void;

package/dist/utils/search-cache.js

@@ -0,0 +1,41 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { listFiles } from "./files.js";
+const CACHE_FILE = "search-cache.json";
+/**
+ * Compute a fingerprint of all .md files in the vault based on paths and mtimes.
+ * Changes when files are added, removed, or modified.
+ */
+export function computeFingerprint(contentPath, folder) {
+    const files = listFiles(contentPath, { folder, ext: "md" });
+    const entries = [];
+    for (const file of files) {
+        const stat = fs.statSync(path.join(contentPath, file));
+        entries.push(`${file}:${stat.mtimeMs}`);
+    }
+    return crypto.createHash("md5").update(entries.join("\n")).digest("hex");
+}
+/**
+ * Load cached search index if the fingerprint matches.
+ * Returns null if no cache, fingerprint mismatch, or corrupted data.
+ */
+export function loadSearchCache(configPath, currentFingerprint) {
+    const cachePath = path.join(configPath, CACHE_FILE);
+    try {
+        const raw = fs.readFileSync(cachePath, "utf-8");
+        const data = JSON.parse(raw);
+        if (data.fingerprint !== currentFingerprint)
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save search index cache to disk.
+ */
+export function saveSearchCache(configPath, data) {
+    fs.writeFileSync(path.join(configPath, CACHE_FILE), JSON.stringify(data));
+}

package/dist/utils/test-helpers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Create a temporary vault for testing.
+ * .napkin/ is the vault root — all content lives inside it.
+ * Returns:
+ *   - path: parent dir (pass to --vault for commands, findVault walks up from here)
+ *   - vaultPath: the .napkin/ dir (pass directly to utility functions like listFiles)
+ *   - cleanup: removes everything
+ */
+export declare function createTempVault(files?: Record<string, string>): {
+    path: string;
+    vaultPath: string;
+    cleanup: () => void;
+};

package/dist/utils/test-helpers.js

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { DEFAULT_CONFIG, saveConfig } from "./config.js";
+/**
+ * Create a temporary vault for testing.
+ * .napkin/ is the vault root — all content lives inside it.
+ * Returns:
+ *   - path: parent dir (pass to --vault for commands, findVault walks up from here)
+ *   - vaultPath: the .napkin/ dir (pass directly to utility functions like listFiles)
+ *   - cleanup: removes everything
+ */
+export function createTempVault(files) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "napkin-test-"));
+    // .napkin/ IS the vault root
+    const napkinDir = path.join(tmpDir, ".napkin");
+    fs.mkdirSync(napkinDir, { recursive: true });
+    // Write config.json which also syncs .obsidian/
+    const testConfig = {
+        ...DEFAULT_CONFIG,
+        daily: {
+            ...DEFAULT_CONFIG.daily,
+            folder: "Inbox/Daily",
+        },
+    };
+    saveConfig(napkinDir, testConfig);
+    // Write files inside .napkin/ (the vault root)
+    if (files) {
+        for (const [filePath, content] of Object.entries(files)) {
+            const full = path.join(napkinDir, filePath);
+            fs.mkdirSync(path.dirname(full), { recursive: true });
+            fs.writeFileSync(full, content);
+        }
+    }
+    return {
+        path: tmpDir,
+        vaultPath: napkinDir,
+        cleanup: () => fs.rmSync(tmpDir, { recursive: true, force: true }),
+    };
+}

package/dist/utils/vault.d.ts

@@ -0,0 +1,21 @@
+export interface VaultInfo {
+    /** Vault display name (derived from content root directory) */
+    name: string;
+    /** Where vault content lives (project root, parent of .napkin/) */
+    contentPath: string;
+    /** Where config.json lives (always the .napkin/ directory) */
+    configPath: string;
+    /** Where .obsidian/ directory lives */
+    obsidianPath: string;
+}
+/**
+ * Walk up from startDir looking for .napkin/ (or .obsidian/.napkin/ for nested layout).
+ * Falls back to the global vault configured in $XDG_CONFIG_HOME/napkin/config.json.
+ * Creates a bare vault at the starting directory as a last resort.
+ */
+export declare function findVault(startDir?: string): VaultInfo;
+/**
+ * Read a JSON config file from .obsidian/ directory.
+ * Returns parsed JSON or null if file doesn't exist.
+ */
+export declare function getVaultConfig(obsidianPath: string, configFile: string): Record<string, unknown> | null;

package/dist/utils/vault.js

@@ -0,0 +1,144 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/**
+ * Walk up from startDir looking for .napkin/ (or .obsidian/.napkin/ for nested layout).
+ * Falls back to the global vault configured in $XDG_CONFIG_HOME/napkin/config.json.
+ * Creates a bare vault at the starting directory as a last resort.
+ */
+export function findVault(startDir) {
+    let dir = path.resolve(startDir || process.cwd());
+    const root = path.parse(dir).root;
+    const startingDir = dir;
+    while (true) {
+        const napkinDir = path.join(dir, ".napkin");
+        if (fs.existsSync(napkinDir) && fs.statSync(napkinDir).isDirectory()) {
+            return resolveVaultLayout(napkinDir, dir);
+        }
+        // Check for nested layout: .obsidian/.napkin/
+        const nestedNapkin = path.join(dir, ".obsidian", ".napkin");
+        if (fs.existsSync(nestedNapkin) &&
+            fs.statSync(nestedNapkin).isDirectory()) {
+            return resolveVaultLayout(nestedNapkin, dir);
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir || dir === root) {
+            break;
+        }
+        dir = parent;
+    }
+    // Fall back to global vault from user config
+    const globalVault = getGlobalConfigVault();
+    if (globalVault) {
+        return resolveVaultLayout(globalVault, path.dirname(globalVault));
+    }
+    // No vault found — create a bare one at the starting directory
+    return createBareVault(startingDir);
+}
+/**
+ * Check for a global vault configured in the user's config directory.
+ * Reads the `vault` field from $XDG_CONFIG_HOME/napkin/config.json
+ * (defaults to ~/.config/napkin/config.json).
+ *
+ * Returns the .napkin/ path if a valid vault is configured, null otherwise.
+ */
+function getGlobalConfigVault() {
+    const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+    const configPath = path.join(configHome, "napkin", "config.json");
+    if (!fs.existsSync(configPath))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        if (!raw.vault)
+            return null;
+        const vaultPath = raw.vault === "~" || raw.vault.startsWith("~/")
+            ? path.join(os.homedir(), raw.vault.slice(1))
+            : path.resolve(path.dirname(configPath), raw.vault);
+        const napkinDir = path.join(vaultPath, ".napkin");
+        if (fs.existsSync(napkinDir))
+            return napkinDir;
+    }
+    catch {
+        // invalid config
+    }
+    return null;
+}
+/**
+ * Create a bare vault at the given directory.
+ * Sibling layout: .napkin/ (config) + .obsidian/ + NAPKIN.md all in projectDir.
+ */
+function createBareVault(projectDir) {
+    const napkinDir = path.join(projectDir, ".napkin");
+    fs.mkdirSync(napkinDir, { recursive: true });
+    const configFile = path.join(napkinDir, "config.json");
+    if (!fs.existsSync(configFile)) {
+        fs.writeFileSync(configFile, JSON.stringify({
+            overview: { depth: 3, keywords: 8 },
+            search: { limit: 30, snippetLines: 0 },
+            daily: { folder: "daily", format: "YYYY-MM-DD" },
+            vault: { root: "..", obsidian: "../.obsidian" },
+        }, null, 2));
+    }
+    const napkinMd = path.join(projectDir, "NAPKIN.md");
+    if (!fs.existsSync(napkinMd)) {
+        fs.writeFileSync(napkinMd, "");
+    }
+    const obsidianDir = path.join(projectDir, ".obsidian");
+    if (!fs.existsSync(obsidianDir)) {
+        fs.mkdirSync(obsidianDir, { recursive: true });
+    }
+    return {
+        name: path.basename(projectDir),
+        contentPath: projectDir,
+        configPath: napkinDir,
+        obsidianPath: obsidianDir,
+    };
+}
+/**
+ * Resolve vault layout from .napkin/config.json vault paths.
+ * If no vault config exists, defaults to sibling layout (content in project dir).
+ */
+function resolveVaultLayout(napkinDir, projectDir) {
+    const configPath = path.join(napkinDir, "config.json");
+    let vaultConfig;
+    try {
+        const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        vaultConfig = raw.vault;
+    }
+    catch {
+        // no config or invalid — use defaults
+    }
+    if (vaultConfig?.root) {
+        const contentPath = path.resolve(napkinDir, vaultConfig.root);
+        const obsidianPath = vaultConfig.obsidian
+            ? path.resolve(napkinDir, vaultConfig.obsidian)
+            : path.join(contentPath, ".obsidian");
+        return {
+            name: path.basename(contentPath),
+            contentPath,
+            configPath: napkinDir,
+            obsidianPath,
+        };
+    }
+    // Legacy: embedded layout — .napkin/ is the vault root (no vault.root in config)
+    return {
+        name: path.basename(projectDir),
+        contentPath: napkinDir,
+        configPath: napkinDir,
+        obsidianPath: path.join(napkinDir, ".obsidian"),
+    };
+}
+/**
+ * Read a JSON config file from .obsidian/ directory.
+ * Returns parsed JSON or null if file doesn't exist.
+ */
+export function getVaultConfig(obsidianPath, configFile) {
+    const configPath = path.join(obsidianPath, configFile);
+    try {
+        const content = fs.readFileSync(configPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@cad0p/napkin",
+  "version": "0.8.1",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "description": "🧻 Knowledge system for agents. Local-first, file-based, progressively disclosed.",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "napkin": "./dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "dev": "bun run src/main.ts",
+    "build:bun": "bun build --compile src/main.ts --outfile napkin",
+    "build:bun-linux": "bun build --compile --target=bun-linux-x64 src/main.ts --outfile napkin-linux-x64",
+    "build:bun-mac-arm": "bun build --compile --target=bun-darwin-arm64 src/main.ts --outfile napkin-darwin-arm64",
+    "build:bun-mac-x64": "bun build --compile --target=bun-darwin-x64 src/main.ts --outfile napkin-darwin-x64",
+    "test": "bun test",
+    "format": "bunx biome format --write src/",
+    "lint": "bunx biome lint src/",
+    "check": "bunx biome check src/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cad0p/napkin.git"
+  },
+  "homepage": "https://github.com/cad0p/napkin#readme",
+  "bugs": {
+    "url": "https://github.com/cad0p/napkin/issues"
+  },
+  "keywords": [
+    "obsidian",
+    "cli",
+    "markdown",
+    "vault",
+    "notes",
+    "tasks",
+    "tags",
+    "search",
+    "local-first"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.6.0",
+    "typescript": "^5.8.0"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "gray-matter": "^4.0.3",
+    "jexl": "^2.3.0",
+    "js-yaml": "^4.1.0",
+    "minisearch": "^7.2.0",
+    "sql.js": "^1.14.0"
+  },
+  "optionalDependencies": {
+    "glimpseui": "^0.3.7"
+  },
+  "trustedDependencies": [
+    "glimpseui"
+  ]
+}