napkin-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Liv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# napkin
+
+🧻 Obsidian-compatible CLI for agents.
+
+## Install
+
+```bash
+npm install -g napkin
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/Michaelliv/napkin.git
+cd napkin
+bun install
+bun run build:bun
+```
+
+## Usage
+
+Run commands from inside an Obsidian vault (any directory containing `.obsidian/`):
+
+```bash
+cd ~/my-vault
+napkin vault
+```
+
+Or specify the vault path:
+
+```bash
+napkin --vault ~/my-vault vault
+```
+
+### Global Flags
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON |
+| `-q, --quiet` | Suppress output |
+| `--vault <path>` | Vault path (default: auto-detect from cwd) |
+| `--copy` | Copy output to clipboard |
+
+## Commands
+
+### Vault
+
+```bash
+napkin vault                          # Show vault info (name, path, files, folders, size)
+```
+
+### Files & Folders
+
+```bash
+napkin file <name>                    # Show file info
+napkin files                          # List all files
+napkin files --ext md                 # Filter by extension
+napkin files --folder Projects        # Filter by folder
+napkin files --total                  # Count files
+napkin folders                        # List folders
+```
+
+### File CRUD
+
+```bash
+napkin read <file>                    # Read file contents
+napkin create --name "Note" --content "Hello"
+napkin create --path "Projects/new" --template "Meeting Note"
+napkin append --file "Note" --content "More text"
+napkin prepend --file "Note" --content "Top line"
+napkin move --file "Note" --to Archive
+napkin rename --file "Note" --name "Renamed"
+napkin delete --file "Note"           # Move to .trash
+napkin delete --file "Note" --permanent
+```
+
+### Daily Notes
+
+Reads config from `.obsidian/daily-notes.json` (folder, format, template).
+
+```bash
+napkin daily                          # Create + open today's daily note
+napkin daily:path                     # Print daily note path
+napkin daily:read                     # Print daily note contents
+napkin daily:append --content "- [ ] Buy groceries"
+napkin daily:prepend --content "## Morning"
+```
+
+### Search
+
+```bash
+napkin search --query "meeting"       # Find files matching text
+napkin search --query "TODO" --path Projects
+napkin search --query "bug" --total   # Count matches
+napkin search:context --query "TODO"  # Grep-style file:line:text output
+```
+
+### Tasks
+
+```bash
+napkin tasks                          # List all tasks
+napkin tasks --todo                   # Incomplete only
+napkin tasks --done                   # Completed only
+napkin tasks --daily                  # Today's daily note tasks
+napkin tasks --file "Project A"       # Tasks in specific file
+napkin tasks --verbose                # Group by file with line numbers
+napkin task --file "note" --line 3    # Show task info
+napkin task --file "note" --line 3 --toggle   # Toggle ✓/○
+napkin task --file "note" --line 3 --done     # Mark done
+napkin task --ref "note.md:3" --todo          # Mark todo
+```
+
+### Tags
+
+```bash
+napkin tags                           # List all tags
+napkin tags --counts                  # With occurrence counts
+napkin tags --sort count              # Sort by frequency
+napkin tag --name "project"           # Tag info
+napkin tag --name "project" --verbose # With file list
+```
+
+### Properties (Frontmatter)
+
+```bash
+napkin properties                     # List all properties in vault
+napkin properties --file "note"       # Properties for a file
+napkin properties --counts            # With occurrence counts
+napkin property:read --file "note" --name title
+napkin property:set --file "note" --name status --value done
+napkin property:remove --file "note" --name status
+```
+
+### Links
+
+```bash
+napkin backlinks --file "note"        # Files linking to this file
+napkin links --file "note"            # Outgoing links from file
+napkin unresolved                     # Broken links in vault
+napkin orphans                        # Files with no incoming links
+napkin deadends                       # Files with no outgoing links
+```
+
+### Outline
+
+```bash
+napkin outline --file "note"          # Headings (tree format)
+napkin outline --file "note" --format md
+napkin outline --file "note" --format json
+```
+
+### Templates
+
+```bash
+napkin templates                      # List templates
+napkin template:read --name "Daily Note"
+napkin template:read --name "Meeting" --resolve --title "Standup"
+```
+
+### Word Count
+
+```bash
+napkin wordcount --file "note"        # Words + characters
+napkin wordcount --file "note" --words
+```
+
+### Agent Onboarding
+
+```bash
+napkin onboard                        # Print agent instructions
+```
+
+## File Resolution
+
+Files can be referenced two ways:
+- **By name** (wikilink-style): `--file "Active Projects"` — searches all `.md` files by basename
+- **By path**: `--file "Projects/Active Projects.md"` — exact path from vault root
+
+## For AI Agents
+
+Every command supports `--json` for structured output. Run `napkin onboard` to get copy-paste instructions for your agent config.
+
+## Development
+
+```bash
+bun install
+bun run dev -- vault --json      # Run in dev mode
+bun test                         # Run tests
+bun run check                    # Lint + format
+```
+
+## License
+
+MIT

package/dist/commands/aliases.d.ts

@@ -0,0 +1,7 @@
+import { type OutputOptions } from "../utils/output.js";
+export declare function aliases(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    total?: boolean;
+    verbose?: boolean;
+}): Promise<void>;

package/dist/commands/aliases.js

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { listFiles, resolveFile } from "../utils/files.js";
+import { parseFrontmatter } from "../utils/frontmatter.js";
+import { dim, output } from "../utils/output.js";
+import { findVault } from "../utils/vault.js";
+function collectAliases(vaultPath, fileFilter) {
+    const files = fileFilter
+        ? (() => {
+            const r = resolveFile(vaultPath, fileFilter);
+            return r ? [r] : [];
+        })()
+        : listFiles(vaultPath, { ext: "md" });
+    const results = [];
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(vaultPath, file), "utf-8");
+        const { properties } = parseFrontmatter(content);
+        const aliases = properties.aliases;
+        if (Array.isArray(aliases)) {
+            for (const a of aliases)
+                results.push({ alias: String(a), file });
+        }
+        else if (typeof aliases === "string" && aliases) {
+            results.push({ alias: aliases, file });
+        }
+    }
+    return results;
+}
+export async function aliases(opts) {
+    const v = findVault(opts.vault);
+    const result = collectAliases(v.path, opts.file);
+    output(opts, {
+        json: () => {
+            if (opts.total)
+                return { total: result.length };
+            if (opts.verbose)
+                return { aliases: result };
+            return { aliases: result.map((r) => r.alias) };
+        },
+        human: () => {
+            if (opts.total) {
+                console.log(result.length);
+            }
+            else {
+                for (const r of result) {
+                    console.log(opts.verbose ? `${r.alias}\t${dim(r.file)}` : r.alias);
+                }
+            }
+        },
+    });
+}

package/dist/commands/bases.d.ts

@@ -0,0 +1,23 @@
+import { type OutputOptions } from "../utils/output.js";
+export declare function bases(opts: OutputOptions & {
+    vault?: string;
+}): Promise<void>;
+export declare function baseViews(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    path?: string;
+}): Promise<void>;
+export declare function baseQuery(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    path?: string;
+    view?: string;
+    format?: string;
+}): Promise<void>;
+export declare function baseCreate(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    path?: string;
+    name?: string;
+    content?: string;
+}): Promise<void>;

package/dist/commands/bases.js

@@ -0,0 +1,192 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildDatabase, parseBaseFile, queryBase } from "../utils/bases.js";
+import { EXIT_USER_ERROR } from "../utils/exit-codes.js";
+import { listFiles } from "../utils/files.js";
+import { bold, dim, error, output, success, } from "../utils/output.js";
+import { findVault } from "../utils/vault.js";
+export async function bases(opts) {
+    const v = findVault(opts.vault);
+    const files = listFiles(v.path).filter((f) => f.endsWith(".base"));
+    output(opts, {
+        json: () => ({ bases: files }),
+        human: () => {
+            if (files.length === 0) {
+                console.log("No .base files found");
+            }
+            else {
+                for (const f of files)
+                    console.log(f);
+            }
+        },
+    });
+}
+export async function baseViews(opts) {
+    const v = findVault(opts.vault);
+    const baseFile = resolveBaseFile(v.path, opts);
+    if (!baseFile) {
+        error("No base file specified. Use --file or --path");
+        process.exit(EXIT_USER_ERROR);
+    }
+    const content = fs.readFileSync(path.join(v.path, baseFile), "utf-8");
+    const config = parseBaseFile(content);
+    const views = (config.views || []).map((view) => ({
+        name: view.name || "(unnamed)",
+        type: view.type,
+    }));
+    output(opts, {
+        json: () => ({ views }),
+        human: () => {
+            for (const view of views) {
+                console.log(`${bold(view.name)}  ${dim(view.type)}`);
+            }
+        },
+    });
+}
+export async function baseQuery(opts) {
+    const v = findVault(opts.vault);
+    const baseFile = resolveBaseFile(v.path, opts);
+    if (!baseFile) {
+        error("No base file specified. Use --file or --path");
+        process.exit(EXIT_USER_ERROR);
+    }
+    const content = fs.readFileSync(path.join(v.path, baseFile), "utf-8");
+    const config = parseBaseFile(content);
+    const db = await buildDatabase(v.path);
+    try {
+        // Derive thisFile from the base file path
+        const thisFile = baseFile
+            ? {
+                name: path.basename(baseFile),
+                path: baseFile,
+                folder: path.dirname(baseFile),
+            }
+            : undefined;
+        const result = await queryBase(db, config, opts.view, thisFile);
+        const fmt = opts.format || "json";
+        // Apply displayNames to columns for output
+        const displayCols = result.columns.map((c) => result.displayNames?.[c] || c);
+        output(opts, {
+            json: () => {
+                if (fmt === "paths") {
+                    const pathIdx = result.columns.indexOf("path");
+                    return { paths: result.rows.map((r) => r[pathIdx]) };
+                }
+                // Convert to array of objects
+                const rows = result.rows.map((row) => {
+                    const obj = {};
+                    for (let i = 0; i < result.columns.length; i++) {
+                        obj[result.columns[i]] = row[i];
+                    }
+                    return obj;
+                });
+                const out = { columns: result.columns, rows };
+                if (result.displayNames &&
+                    Object.keys(result.displayNames).length > 0) {
+                    out.displayNames = result.displayNames;
+                }
+                if (result.groups) {
+                    out.groups = result.groups.map((g) => ({
+                        key: g.key,
+                        rows: g.rows.map((row) => {
+                            const obj = {};
+                            for (let i = 0; i < result.columns.length; i++) {
+                                obj[result.columns[i]] = row[i];
+                            }
+                            return obj;
+                        }),
+                    }));
+                }
+                if (result.summaries)
+                    out.summaries = result.summaries;
+                return out;
+            },
+            human: () => {
+                if (result.rows.length === 0) {
+                    console.log("No results");
+                    return;
+                }
+                if (fmt === "paths") {
+                    const pathIdx = result.columns.indexOf("path");
+                    for (const row of result.rows)
+                        console.log(row[pathIdx]);
+                    return;
+                }
+                if (fmt === "csv" || fmt === "tsv") {
+                    const sep = fmt === "csv" ? "," : "\t";
+                    console.log(displayCols.join(sep));
+                    for (const row of result.rows) {
+                        console.log(row.map((v) => (v === null ? "" : String(v))).join(sep));
+                    }
+                    return;
+                }
+                if (fmt === "md") {
+                    console.log(`| ${displayCols.join(" | ")} |`);
+                    console.log(`| ${displayCols.map(() => "---").join(" | ")} |`);
+                    for (const row of result.rows) {
+                        console.log(`| ${row.map((v) => (v === null ? "" : String(v))).join(" | ")} |`);
+                    }
+                    return;
+                }
+                // Default: table-like
+                for (const row of result.rows) {
+                    const obj = {};
+                    for (let i = 0; i < result.columns.length; i++) {
+                        if (row[i] !== null)
+                            obj[result.columns[i]] = row[i];
+                    }
+                    console.log(JSON.stringify(obj));
+                }
+            },
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+export async function baseCreate(opts) {
+    const v = findVault(opts.vault);
+    if (!opts.name) {
+        error("No name specified. Use --name <name>");
+        process.exit(EXIT_USER_ERROR);
+    }
+    // Create a new note (item in the base)
+    const targetPath = opts.path
+        ? opts.path.endsWith(".md")
+            ? opts.path
+            : `${opts.path}/${opts.name}.md`
+        : `${opts.name}.md`;
+    const fullPath = path.join(v.path, targetPath);
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, opts.content || "");
+    output(opts, {
+        json: () => ({ path: targetPath, created: true }),
+        human: () => success(`Created ${targetPath}`),
+    });
+}
+function resolveBaseFile(vaultPath, opts) {
+    if (opts.path) {
+        const p = opts.path.endsWith(".base") ? opts.path : `${opts.path}.base`;
+        if (fs.existsSync(path.join(vaultPath, p)))
+            return p;
+        return null;
+    }
+    if (opts.file) {
+        // Search for .base file by name
+        const allFiles = listFiles(vaultPath).filter((f) => f.endsWith(".base"));
+        const target = opts.file.toLowerCase();
+        for (const f of allFiles) {
+            const basename = path.basename(f, ".base").toLowerCase();
+            if (basename === target)
+                return f;
+        }
+        // Try with .base extension
+        const withExt = opts.file.endsWith(".base")
+            ? opts.file
+            : `${opts.file}.base`;
+        if (fs.existsSync(path.join(vaultPath, withExt)))
+            return withExt;
+        return null;
+    }
+    return null;
+}

package/dist/commands/bookmarks.d.ts

@@ -0,0 +1,15 @@
+import { type OutputOptions } from "../utils/output.js";
+export declare function bookmarks(opts: OutputOptions & {
+    vault?: string;
+    total?: boolean;
+    verbose?: boolean;
+}): Promise<void>;
+export declare function bookmark(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    subpath?: string;
+    folder?: string;
+    search?: string;
+    url?: string;
+    title?: string;
+}): Promise<void>;

package/dist/commands/bookmarks.js

@@ -0,0 +1,82 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { EXIT_USER_ERROR } from "../utils/exit-codes.js";
+import { dim, error, output, success, } from "../utils/output.js";
+import { findVault } from "../utils/vault.js";
+function readBookmarks(vaultPath) {
+    const configPath = path.join(vaultPath, ".obsidian", "bookmarks.json");
+    try {
+        const content = fs.readFileSync(configPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+}
+function writeBookmarks(vaultPath, bookmarks) {
+    const configPath = path.join(vaultPath, ".obsidian", "bookmarks.json");
+    fs.writeFileSync(configPath, JSON.stringify(bookmarks, null, 2));
+}
+function flattenBookmarks(items) {
+    const result = [];
+    for (const item of items) {
+        if (item.type === "group" && item.items) {
+            result.push(...flattenBookmarks(item.items));
+        }
+        else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+export async function bookmarks(opts) {
+    const v = findVault(opts.vault);
+    const items = readBookmarks(v.path);
+    const flat = flattenBookmarks(items);
+    output(opts, {
+        json: () => (opts.total ? { total: flat.length } : { bookmarks: flat }),
+        human: () => {
+            if (opts.total) {
+                console.log(flat.length);
+            }
+            else {
+                for (const b of flat) {
+                    const label = b.title || b.path || b.query || b.url || "(untitled)";
+                    console.log(opts.verbose ? `${label}\t${dim(b.type)}` : label);
+                }
+            }
+        },
+    });
+}
+export async function bookmark(opts) {
+    const v = findVault(opts.vault);
+    let entry;
+    if (opts.file) {
+        entry = {
+            type: "file",
+            path: opts.file,
+            title: opts.title,
+            subpath: opts.subpath,
+        };
+    }
+    else if (opts.folder) {
+        entry = { type: "folder", path: opts.folder, title: opts.title };
+    }
+    else if (opts.search) {
+        entry = { type: "search", query: opts.search, title: opts.title };
+    }
+    else if (opts.url) {
+        entry = { type: "url", url: opts.url, title: opts.title };
+    }
+    else {
+        error("Specify --file, --folder, --search, or --url to bookmark");
+        process.exit(EXIT_USER_ERROR);
+    }
+    const items = readBookmarks(v.path);
+    items.push(entry);
+    writeBookmarks(v.path, items);
+    output(opts, {
+        json: () => ({ added: entry }),
+        human: () => success(`Bookmarked ${entry.path || entry.query || entry.url}`),
+    });
+}

package/dist/commands/canvas.d.ts

@@ -0,0 +1,49 @@
+import { type OutputOptions } from "../utils/output.js";
+export declare function canvases(opts: OutputOptions & {
+    vault?: string;
+    total?: boolean;
+}): Promise<void>;
+export declare function canvasRead(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+}): Promise<void>;
+export declare function canvasNodes(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    type?: string;
+}): Promise<void>;
+export declare function canvasCreate(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    path?: string;
+}): Promise<void>;
+export declare function canvasAddNode(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    type?: string;
+    text?: string;
+    noteFile?: string;
+    subpath?: string;
+    url?: string;
+    label?: string;
+    x?: string;
+    y?: string;
+    width?: string;
+    height?: string;
+    color?: string;
+}): Promise<void>;
+export declare function canvasAddEdge(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    from?: string;
+    to?: string;
+    fromSide?: string;
+    toSide?: string;
+    label?: string;
+    color?: string;
+}): Promise<void>;
+export declare function canvasRemoveNode(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    id?: string;
+}): Promise<void>;