pathnote 0.0.0-stage → 0.2.0

package/src/mcp.js

@@ -0,0 +1,100 @@
+// The MCP tools the AI uses. Each call does its work and tells the viewer what happened.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+const reason = z.string().optional().describe('One short sentence on why you are doing this. Shown to the user in the Pathnote viewer.');
+const text = s => ({ content: [{ type: 'text', text: s }] });
+const fail = e => ({ content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true });
+
+export function createServer({ ws, history, hub, version }) {
+  const server = new McpServer({ name: 'pathnote', version });
+  const where = `Connected folders: ${ws.roots.join(', ')}. Use full paths.`;
+
+  server.registerTool('list_files', {
+    title: 'List a folder',
+    description: `List what is inside a folder (folders end with "/"). Without a folder, lists the connected folders. ${where}`,
+    inputSchema: { folder: z.string().optional(), reason }
+  }, async ({ folder, reason }) => {
+    try {
+      if (!folder) return text(ws.roots.join('\n'));
+      const abs = ws.resolve(folder);
+      const items = await ws.list(abs);
+      await hub.emit({ type: 'list', path: abs, reason });
+      return text(items.join('\n') || '(empty folder)');
+    } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('search_files', {
+    title: 'Search files',
+    description: `Search text files and documents (PDF, Word, PowerPoint, Excel, Hangul) in the connected folders for words. Returns the best matching paths with a snippet each. ${where}`,
+    inputSchema: { query: z.string().describe('Words to look for'), reason }
+  }, async ({ query, reason }) => {
+    try {
+      const hits = await ws.search(query);
+      await hub.emit({ type: 'search', query, hits: hits.map(h => h.path), reason });
+      return text(hits.length ? hits.map(h => `${h.path}\n  ${h.snippet}`).join('\n') : 'No matches.');
+    } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('read_file', {
+    title: 'Read a file',
+    description: `Read a file: text files (up to 2 MB) as they are, PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx) and Hangul (.hwpx) as their text, and pictures (.png, .jpg, .gif, .webp, .heic) as images you can see. ${where}`,
+    inputSchema: { path: z.string(), reason }
+  }, async ({ path, reason }) => {
+    try {
+      const abs = ws.resolve(path);
+      const file = await ws.open(abs);
+      await hub.emit({ type: 'read', path: abs, reason });
+      if (file.kind === 'image') return { content: [{ type: 'image', data: file.data, mimeType: file.mimeType }] };
+      return text(file.text);
+    } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('write_file', {
+    title: 'Write a file',
+    description: `Create a text file, or replace a text file's whole text (not documents or pictures). The user can undo this from the Pathnote viewer. In markdown notes, link the notes you used with [[Note name]]. ${where}`,
+    inputSchema: { path: z.string(), content: z.string(), reason }
+  }, async ({ path, content, reason }) => {
+    try {
+      const abs = ws.resolve(path);
+      const before = await ws.readOrNull(abs);
+      const change = await history.record(abs, before, content, before === null ? 'create' : 'write');
+      await ws.write(abs, content);
+      await hub.emit({ type: 'write', path: abs, created: before === null, changeId: change.id, reason });
+      return text(`${before === null ? 'Created' : 'Replaced'} ${abs}.`);
+    } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('edit_file', {
+    title: 'Edit a file',
+    description: `Replace one exact piece of text in a file. \`find\` must appear exactly once. The user can undo this from the Pathnote viewer. ${where}`,
+    inputSchema: { path: z.string(), find: z.string().min(1), replace: z.string(), reason }
+  }, async ({ path, find, replace, reason }) => {
+    try {
+      const abs = ws.resolve(path);
+      const before = await ws.read(abs);
+      const count = before.split(find).length - 1;
+      if (count !== 1) throw new Error(count ? `The text appears ${count} times; include more of it so it is unique.` : 'The text was not found.');
+      const after = before.replace(find, () => replace);
+      const change = await history.record(abs, before, after, 'edit');
+      await ws.write(abs, after);
+      await hub.emit({ type: 'edit', path: abs, changeId: change.id, reason });
+      return text(`Edited ${abs}.`);
+    } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('move_file', {
+    title: 'Move a file or folder',
+    description: `Move or rename a file or folder (any type, including pictures and videos) to a new full path. Missing parent folders are created. Never overwrites an existing path. The user can undo this from the Pathnote viewer. ${where}`,
+    inputSchema: { from: z.string(), to: z.string(), reason }
+  }, async ({ from, to, reason }) => {
+    try {
+      const moved = await ws.move(from, to);
+      const change = await history.recordMove(moved.from, moved.to);
+      await hub.emit({ type: 'move', path: moved.to, from: moved.from, dir: moved.dir, changeId: change.id, reason });
+      return text(`Moved ${moved.from} to ${moved.to}.`);
+    } catch (e) { return fail(e); }
+  });
+
+  return server;
+}

package/src/workspace.js

@@ -0,0 +1,244 @@
+// The folders Pathnote may touch. Every path from the AI is checked against them: it must be
+// inside one of the folders (after following symlinks), not in a skipped folder, and not a
+// file that usually holds secrets.
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isDocument, isImage, documentText, imageContent, MAX_DOC } from './documents.js';
+
+const SKIP = new Set(['.git', '.obsidian', '.trash', '.Trash', 'node_modules', '.build', 'build', 'DerivedData', 'dist', '.wrangler', '.venv', '__pycache__']);
+// Word and LibreOffice leave these lock files next to open documents
+const LOCK = /^(~\$|\.~lock\.)/;
+const SECRET_DIRS = new Set(['secrets', '.ssh', '.gnupg', '.aws']);
+const SECRET_FILE = /^(\.env(\..*)?|.*\.(pem|p8|p12|key|keystore|jks)|id_(rsa|ed25519|ecdsa)(\.pub)?|credentials\.json|token\.json|client_secret.*\.json|\.npmrc|\.netrc)$/i;
+const TEXT = /\.(md|mdx|txt|markdown|csv|tsv|json|jsonc|ya?ml|toml|ini|cfg|conf|xml|html?|css|scss|js|mjs|cjs|jsx|ts|tsx|py|rb|go|rs|java|kt|swift|m|h|c|cc|cpp|hpp|cs|php|sh|zsh|bash|sql|r|lua|tex|bib|srt|vtt|log)$/i;
+const LINK = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/g;
+const MAX_READ = 2 * 1024 * 1024;
+const MAX_SEARCH = 512 * 1024;
+export const MAX_NODES = 6000;
+
+const BLOCKED = 'macOS is blocking access to this folder. Allow it in System Settings → Privacy & Security → Files and Folders (for the app that runs Pathnote), then try again.';
+
+// macOS holds file calls on protected folders (Desktop, Downloads, iCloud Drive) until the user
+// answers a permission prompt, possibly forever. Give up after `ms` instead of hanging.
+const timeout = (promise, ms) => Promise.race([promise, new Promise((_, no) => setTimeout(() => no(Object.assign(new Error(BLOCKED), { code: 'EBLOCKED' })), ms))]);
+
+const exists = p => fs.access(p).then(() => true, () => false);
+
+// First file under `dir` that looks like it holds secrets, or null
+async function findSecret(dir) {
+  for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, e.name);
+    if (SECRET_FILE.test(e.name) || (e.isDirectory() && SECRET_DIRS.has(e.name))) return abs;
+    if (e.isDirectory()) { const found = await findSecret(abs); if (found) return found; }
+  }
+  return null;
+}
+
+const expand = p => String(p || '').trim().replace(/^~(?=$|\/)/, os.homedir());
+
+export class Workspace {
+  constructor(folders) {
+    this.roots = [...new Set(folders.map(f => path.resolve(expand(f))))];
+    this.id = this.roots.join('\n');
+  }
+
+  // Full path for something the AI named. Relative paths are allowed when there is one folder.
+  resolve(p) {
+    let s = expand(p);
+    if (!s) throw new Error('Path is empty.');
+    if (!path.isAbsolute(s)) {
+      if (this.roots.length > 1) throw new Error(`Use a full path, e.g. ${path.join(this.roots[0], s)}`);
+      s = path.join(this.roots[0], s);
+    }
+    const abs = path.resolve(s);
+    const root = this.rootOf(abs);
+    if (!root) throw new Error(`"${p}" is outside the connected folders: ${this.roots.join(', ')}`);
+    const parts = path.relative(root, abs).split(path.sep);
+    if (parts.some(x => SKIP.has(x))) throw new Error(`"${p}" is in a folder Pathnote skips.`);
+    if (parts.some(x => SECRET_DIRS.has(x)) || SECRET_FILE.test(path.basename(abs))) throw new Error(`"${p}" looks like it holds secrets, so Pathnote won't open it.`);
+    return abs;
+  }
+
+  rootOf(abs) {
+    return this.roots.find(r => abs === r || abs.startsWith(r + path.sep));
+  }
+
+  // resolve(), then the same check after following symlinks
+  async real(p) {
+    const abs = this.resolve(p);
+    let at = abs;
+    for (;;) {
+      try { at = await timeout(fs.realpath(at), 5000); break; } catch (e) { if (e.code !== 'ENOENT') throw e; at = path.dirname(at); }
+    }
+    const roots = await Promise.all(this.roots.map(r => fs.realpath(r).catch(() => r)));
+    if (!roots.some(r => at === r || at.startsWith(r + path.sep))) throw new Error(`"${p}" leads outside the connected folders.`);
+    return abs;
+  }
+
+  // Immediate contents of a folder; folders end with "/"
+  async list(dir) {
+    const abs = await this.real(dir);
+    const out = [];
+    for (const e of await timeout(fs.readdir(abs, { withFileTypes: true }), 5000)) {
+      if (e.name.startsWith('.') || LOCK.test(e.name) || SKIP.has(e.name) || SECRET_DIRS.has(e.name) || SECRET_FILE.test(e.name)) continue;
+      out.push(e.isDirectory() ? e.name + '/' : e.name);
+    }
+    return out.sort();
+  }
+
+  async read(p) {
+    const abs = await this.real(p);
+    const st = await timeout(fs.stat(abs), 5000);
+    if (st.isDirectory()) throw new Error(`"${p}" is a folder. Use list_files.`);
+    if (st.size > MAX_READ) throw new Error(`"${p}" is ${(st.size / 1048576).toFixed(1)} MB; Pathnote reads files up to 2 MB.`);
+    const buf = await timeout(fs.readFile(abs), 10000);
+    if (buf.subarray(0, 8000).includes(0)) throw new Error(`"${p}" is not a text file.`);
+    return buf.toString('utf8');
+  }
+
+  // Anything the AI can take in: text as is, documents as their text, pictures as images
+  async open(p) {
+    const abs = await this.real(p);
+    if (!isDocument(abs) && !isImage(abs)) return { kind: 'text', text: await this.read(abs) };
+    const st = await timeout(fs.stat(abs), 5000);
+    if (st.size > MAX_DOC) throw new Error(`"${p}" is ${(st.size / 1048576).toFixed(1)} MB; Pathnote opens documents and images up to 50 MB.`);
+    const buf = await timeout(fs.readFile(abs), 15000);
+    if (isImage(abs)) return { kind: 'image', ...(await timeout(imageContent(abs, buf), 20000)) };
+    return { kind: 'document', text: await timeout(documentText(abs, buf), 30000) };
+  }
+
+  // Document text for search, kept until the file changes
+  async docText(abs) {
+    const st = await fs.stat(abs);
+    if (st.size > MAX_DOC) return null;
+    const hit = this.docs?.get(abs);
+    if (hit?.mtime === st.mtimeMs) return hit.text;
+    const text = await timeout(documentText(abs, await fs.readFile(abs)), 15000);
+    (this.docs ??= new Map()).set(abs, { mtime: st.mtimeMs, text });
+    return text;
+  }
+
+  // Read every document's text once in the background, so the first search doesn't wait for it
+  async warm() {
+    for (const it of await this.walk()) {
+      if (it.kind === 'file' && isDocument(it.id)) await this.docText(it.id).catch(() => {});
+    }
+  }
+
+  async readOrNull(p) {
+    try { return await this.read(p); } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+  }
+
+  async write(p, text) {
+    const abs = await this.real(p);
+    if (isDocument(abs) || isImage(abs)) throw new Error(`Pathnote can read ${path.extname(abs)} files but not write them.`);
+    await timeout(fs.mkdir(path.dirname(abs), { recursive: true }), 5000);
+    await timeout(fs.writeFile(abs, text, 'utf8'), 10000);
+  }
+
+  // Move a file or folder (any type) to a new path in the connected folders. Never overwrites,
+  // and refuses folders that hold secret files, since those would leave the protected place.
+  async move(from, to) {
+    const src = await this.real(from), dst = await this.real(to);
+    if (this.roots.includes(src)) throw new Error(`"${from}" is a connected folder itself; move what is inside it instead.`);
+    const st = await timeout(fs.stat(src), 5000);
+    if (await exists(dst)) throw new Error(`"${to}" already exists; Pathnote never overwrites.`);
+    if (dst.startsWith(src + path.sep)) throw new Error(`Can't move "${from}" into itself.`);
+    if (st.isDirectory()) {
+      const secret = await findSecret(src);
+      if (secret) throw new Error(`"${from}" holds a file that looks like a secret (${path.relative(src, secret)}), so Pathnote won't move it.`);
+    }
+    await timeout(fs.mkdir(path.dirname(dst), { recursive: true }), 5000);
+    try {
+      await fs.rename(src, dst);
+    } catch (e) {
+      if (e.code !== 'EXDEV') throw e;
+      // different disk (e.g. iCloud Drive): copy, then remove the original
+      await fs.cp(src, dst, { recursive: true, errorOnExist: true, force: false, preserveTimestamps: true });
+      await fs.rm(src, { recursive: true });
+    }
+    return { from: src, to: dst, dir: st.isDirectory() };
+  }
+
+  async remove(p) {
+    await fs.rm(await this.real(p), { force: true });
+  }
+
+  // Every folder and file under the roots, minus skipped, hidden and secret ones. Stops at MAX_NODES.
+  async walk() {
+    // All folders at once, so several blocked ones cost one timeout, not one each
+    const per = await Promise.all(this.roots.map(async r => {
+      const mine = [{ id: r, kind: 'root', parent: null }];
+      try {
+        await timeout(this.visit(r, mine, MAX_NODES), 4000);
+        return { items: mine };
+      } catch (e) {
+        if (e.code !== 'EBLOCKED') throw e;
+        return { items: mine.slice(0, 1), blocked: r };
+      }
+    }));
+    this.blocked = per.filter(x => x.blocked).map(x => x.blocked);
+    return per.flatMap(x => x.items).slice(0, MAX_NODES);
+  }
+
+  async visit(root, items, max) {
+    const visit = async (dir, depth) => {
+      let entries;
+      try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+      entries.sort((a, b) => a.name.localeCompare(b.name));
+      for (const e of entries) {
+        if (items.length >= max) return;
+        if (e.name.startsWith('.') || LOCK.test(e.name) || SKIP.has(e.name) || SECRET_DIRS.has(e.name) || SECRET_FILE.test(e.name)) continue;
+        const abs = path.join(dir, e.name);
+        if (e.isDirectory()) { items.push({ id: abs, kind: 'dir', parent: dir }); await visit(abs, depth + 1); }
+        else if (e.isFile()) items.push({ id: abs, kind: 'file', parent: dir });
+      }
+    };
+    await visit(root, 1);
+  }
+
+  // Text files and documents ranked by how often the query's words appear, file-name matches counted extra
+  async search(query, limit = 10) {
+    const words = String(query).toLowerCase().split(/\s+/).filter(Boolean);
+    if (!words.length) return [];
+    const hits = [];
+    for (const it of await this.walk()) {
+      if (it.kind !== 'file' || !(TEXT.test(it.id) || isDocument(it.id))) continue;
+      let text;
+      try {
+        if (isDocument(it.id)) text = await this.docText(it.id);
+        else {
+          const st = await fs.stat(it.id);
+          if (st.size > MAX_SEARCH) continue;
+          text = await timeout(fs.readFile(it.id, 'utf8'), 3000);
+        }
+      } catch { continue; }
+      if (!text) continue;
+      const lower = text.toLowerCase(), name = path.basename(it.id).toLowerCase();
+      let score = 0;
+      for (const w of words) { score += lower.split(w).length - 1; if (name.includes(w)) score += 5; }
+      if (!score) continue;
+      const at = Math.max(0, lower.indexOf(words.find(w => lower.includes(w)) ?? words[0]));
+      hits.push({ path: it.id, score, snippet: text.slice(Math.max(0, at - 60), at + 140).replace(/\s+/g, ' ').trim() });
+    }
+    return hits.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+
+  // Folder tree for the viewer, plus [[wikilinks]] between markdown notes (resolved by name, like Obsidian)
+  async graph() {
+    const items = await this.walk();
+    const notes = items.filter(i => i.kind === 'file' && /\.md$/i.test(i.id));
+    const byName = new Map(notes.map(n => [path.basename(n.id, path.extname(n.id)).toLowerCase(), n.id]));
+    const links = [];
+    for (const n of notes) {
+      let text;
+      try { text = await fs.readFile(n.id, 'utf8'); } catch { continue; }
+      for (const m of text.matchAll(LINK)) {
+        const target = byName.get(path.basename(m[1].trim()).toLowerCase());
+        if (target && target !== n.id) links.push([n.id, target]);
+      }
+    }
+    return { roots: this.roots, items, links, blocked: this.blocked, capped: items.length >= MAX_NODES };
+  }
+}