apple-notes-mcp 2.5.7 → 2.5.8

package/build/utils/hashtags.test.js

@@ -1,45 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { parseHashtags } from "../utils/hashtags.js";
-describe("parseHashtags", () => {
-    it("returns [] for empty / nullish input", () => {
-        expect(parseHashtags("")).toEqual([]);
-        expect(parseHashtags(null)).toEqual([]);
-        expect(parseHashtags(undefined)).toEqual([]);
-        expect(parseHashtags("no tags here")).toEqual([]);
-    });
-    it("extracts a single tag", () => {
-        expect(parseHashtags("Buy milk #groceries")).toEqual(["groceries"]);
-    });
-    it("extracts multiple tags in document order", () => {
-        expect(parseHashtags("#work then #home then #travel")).toEqual(["work", "home", "travel"]);
-    });
-    it("strips the leading # and not the rest", () => {
-        expect(parseHashtags("#project_alpha")).toEqual(["project_alpha"]);
-    });
-    it("finds tags inside HTML bodies", () => {
-        expect(parseHashtags("<div>Plan <b>#q3</b> launch</div>")).toEqual(["q3"]);
-    });
-    it("de-duplicates case-insensitively, keeping first-seen casing", () => {
-        expect(parseHashtags("#Work and #work and #WORK")).toEqual(["Work"]);
-    });
-    it("ignores purely numeric tokens (matches Notes behaviour)", () => {
-        expect(parseHashtags("ticket #123 and #4you")).toEqual(["4you"]);
-    });
-    it("does not match mid-word or URL fragments", () => {
-        expect(parseHashtags("foo#bar")).toEqual([]);
-        expect(parseHashtags("see page.html#section for details")).toEqual([]);
-    });
-    it("does not treat numeric HTML entities as tags", () => {
-        // &#8217; is a right single quote entity, not a #8217 tag
-        expect(parseHashtags("It&#8217;s a #plan")).toEqual(["plan"]);
-    });
-    it("matches a tag at the very start of the body", () => {
-        expect(parseHashtags("#start of note")).toEqual(["start"]);
-    });
-    it("handles tags terminated by punctuation", () => {
-        expect(parseHashtags("done: #alpha, #beta; #gamma.")).toEqual(["alpha", "beta", "gamma"]);
-    });
-    it("supports unicode letters in tags", () => {
-        expect(parseHashtags("café trip #café")).toEqual(["café"]);
-    });
-});

package/build/utils/jxa.js

@@ -1,139 +0,0 @@
-/**
- * JXA (JavaScript for Automation) Execution Utilities
- *
- * This module provides an alternative to AppleScript using JavaScript.
- * JXA was introduced in OS X Yosemite and uses the same OSA infrastructure
- * as AppleScript but with JavaScript syntax.
- *
- * Potential advantages over AppleScript:
- * - Standard JavaScript string escaping (simpler than AppleScript)
- * - Better Unicode handling
- * - Familiar syntax for developers
- * - Native JSON support
- *
- * @module utils/jxa
- */
-import { execSync } from "child_process";
-/**
- * Output cap for osascript (JXA). Mirrors the AppleScript executor — Node's 1 MB
- * default truncates large JXA output into an ENOBUFS failure. 64 MB default,
- * overridable via APPLE_NOTES_MCP_MAX_BUFFER. (#16)
- */
-const DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
-function getMaxBuffer() {
-    const raw = process.env.APPLE_NOTES_MCP_MAX_BUFFER;
-    if (raw !== undefined) {
-        const n = Number(raw);
-        if (Number.isFinite(n) && n > 0)
-            return n;
-    }
-    return DEFAULT_MAX_BUFFER_BYTES;
-}
-const DEFAULT_TIMEOUT_MS = 30000;
-/**
- * Escapes a string for safe inclusion in a JXA script.
- *
- * JXA uses standard JavaScript string escaping, which is simpler
- * than AppleScript's escaping requirements.
- *
- * @param str - The string to escape
- * @returns Escaped string safe for JXA embedding
- */
-export function escapeForJXA(str) {
-    if (!str)
-        return "";
-    // Standard JavaScript string escaping
-    return str
-        .replace(/\\/g, "\\\\") // Backslashes first
-        .replace(/"/g, '\\"') // Double quotes
-        .replace(/\n/g, "\\n") // Newlines
-        .replace(/\r/g, "\\r") // Carriage returns
-        .replace(/\t/g, "\\t"); // Tabs
-}
-/**
- * Checks if an error is a timeout error.
- */
-function isTimeoutError(error) {
-    if (error instanceof Error) {
-        const execError = error;
-        return execError.killed === true || execError.signal === "SIGTERM";
-    }
-    return false;
-}
-/**
- * Executes a JXA (JavaScript for Automation) script.
- *
- * JXA scripts are executed via `osascript -l JavaScript`.
- *
- * @param script - The JavaScript code to execute
- * @param options - Execution options
- * @returns Result with success status and output or error
- *
- * @example
- * ```typescript
- * const result = executeJXA(`
- *   const Notes = Application("Notes");
- *   Notes.accounts().map(a => a.name());
- * `);
- * ```
- */
-export function executeJXA(script, options = {}) {
-    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    if (!script || !script.trim()) {
-        return {
-            success: false,
-            output: "",
-            error: "Cannot execute empty JXA script",
-        };
-    }
-    // Escape the script for shell embedding
-    // We use single quotes to wrap, so escape single quotes within
-    const escapedScript = script.trim().replace(/'/g, "'\\''");
-    const command = `osascript -l JavaScript -e '${escapedScript}'`;
-    try {
-        const output = execSync(command, {
-            encoding: "utf8",
-            timeout: timeoutMs,
-            killSignal: "SIGKILL", // reap a wedged osascript reliably (#17)
-            maxBuffer: getMaxBuffer(), // avoid ENOBUFS truncation on large output (#16)
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        return {
-            success: true,
-            output: output.trim(),
-        };
-    }
-    catch (error) {
-        let errorMessage;
-        if (isTimeoutError(error)) {
-            const timeoutSecs = Math.round(timeoutMs / 1000);
-            errorMessage = `Operation timed out after ${timeoutSecs} seconds`;
-        }
-        else if (error instanceof Error) {
-            // Extract meaningful error from stderr
-            const match = error.message.match(/Error: (.+)/);
-            errorMessage = match ? match[1] : error.message;
-        }
-        else {
-            errorMessage = "JXA execution failed with unknown error";
-        }
-        return {
-            success: false,
-            output: "",
-            error: errorMessage,
-        };
-    }
-}
-/**
- * Builds a JXA script that interacts with Notes.app.
- *
- * @param code - JavaScript code to execute within Notes context
- * @returns Complete JXA script
- */
-export function buildNotesJXA(code) {
-    return `
-    const Notes = Application("Notes");
-    Notes.includeStandardAdditions = true;
-    ${code}
-  `;
-}

package/build/utils/jxa.test.js

@@ -1,134 +0,0 @@
-/**
- * Tests for JXA Execution Utilities
- *
- * These tests verify the JXA executor and compare behavior with AppleScript.
- */
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { executeJXA, escapeForJXA, buildNotesJXA } from "./jxa.js";
-// Mock execSync to avoid actual osascript calls
-vi.mock("child_process", () => ({
-    execSync: vi.fn(),
-}));
-import { execSync } from "child_process";
-const mockExecSync = vi.mocked(execSync);
-describe("escapeForJXA", () => {
-    beforeEach(() => {
-        vi.clearAllMocks();
-    });
-    it("returns empty string for null/undefined", () => {
-        expect(escapeForJXA("")).toBe("");
-        expect(escapeForJXA(null)).toBe("");
-        expect(escapeForJXA(undefined)).toBe("");
-    });
-    it("escapes backslashes", () => {
-        expect(escapeForJXA("path\\to\\file")).toBe("path\\\\to\\\\file");
-    });
-    it("escapes double quotes", () => {
-        expect(escapeForJXA('say "hello"')).toBe('say \\"hello\\"');
-    });
-    it("escapes newlines", () => {
-        expect(escapeForJXA("line1\nline2")).toBe("line1\\nline2");
-    });
-    it("escapes tabs", () => {
-        expect(escapeForJXA("col1\tcol2")).toBe("col1\\tcol2");
-    });
-    it("handles complex content", () => {
-        const input = 'John said "Hello\\World"\nNew line';
-        const expected = 'John said \\"Hello\\\\World\\"\\nNew line';
-        expect(escapeForJXA(input)).toBe(expected);
-    });
-    it("preserves single quotes (no escaping needed in double-quoted JS strings)", () => {
-        expect(escapeForJXA("it's working")).toBe("it's working");
-    });
-    it("preserves unicode characters", () => {
-        expect(escapeForJXA("日本語 🎉")).toBe("日本語 🎉");
-    });
-});
-describe("executeJXA", () => {
-    beforeEach(() => {
-        vi.clearAllMocks();
-    });
-    it("returns error for empty script", () => {
-        const result = executeJXA("");
-        expect(result.success).toBe(false);
-        expect(result.error).toContain("empty");
-    });
-    it("executes JXA script via osascript", () => {
-        mockExecSync.mockReturnValue("test output\n");
-        const result = executeJXA("JSON.stringify({test: true})");
-        expect(result.success).toBe(true);
-        expect(result.output).toBe("test output");
-        expect(mockExecSync).toHaveBeenCalledWith(expect.stringContaining("-l JavaScript"), expect.any(Object));
-    });
-    it("handles execution errors", () => {
-        mockExecSync.mockImplementation(() => {
-            throw new Error("Error: Cannot find note");
-        });
-        const result = executeJXA("Notes.notes()");
-        expect(result.success).toBe(false);
-        expect(result.error).toContain("Cannot find note");
-    });
-    describe("hardened executor (#16/#17)", () => {
-        afterEach(() => {
-            delete process.env.APPLE_NOTES_MCP_MAX_BUFFER;
-        });
-        it("passes SIGKILL and a large maxBuffer to execSync", () => {
-            mockExecSync.mockReturnValue("ok");
-            executeJXA("JSON.stringify({})");
-            const opts = mockExecSync.mock.calls[0][1];
-            expect(opts.killSignal).toBe("SIGKILL");
-            expect(opts.maxBuffer).toBe(64 * 1024 * 1024);
-        });
-        it("honors APPLE_NOTES_MCP_MAX_BUFFER override", () => {
-            process.env.APPLE_NOTES_MCP_MAX_BUFFER = "2097152";
-            mockExecSync.mockReturnValue("ok");
-            executeJXA("JSON.stringify({})");
-            const opts = mockExecSync.mock.calls[0][1];
-            expect(opts.maxBuffer).toBe(2097152);
-        });
-    });
-    it("handles timeout errors", () => {
-        const error = new Error("Command failed");
-        error.killed = true;
-        mockExecSync.mockImplementation(() => {
-            throw error;
-        });
-        const result = executeJXA("longRunningScript()", { timeoutMs: 5000 });
-        expect(result.success).toBe(false);
-        expect(result.error).toContain("timed out");
-    });
-});
-describe("buildNotesJXA", () => {
-    it("wraps code with Notes application context", () => {
-        const code = "Notes.accounts().map(a => a.name())";
-        const script = buildNotesJXA(code);
-        expect(script).toContain('Application("Notes")');
-        expect(script).toContain(code);
-    });
-});
-// =============================================================================
-// Comparison Tests: JXA vs AppleScript Escaping
-// =============================================================================
-describe("JXA vs AppleScript escaping comparison", () => {
-    it("JXA handles single quotes without special escaping", () => {
-        // In AppleScript, single quotes need shell escaping: '\''
-        // In JXA, single quotes are fine in double-quoted strings
-        const input = "it's Rob's note";
-        const escaped = escapeForJXA(input);
-        expect(escaped).toBe("it's Rob's note"); // No change needed
-    });
-    it("JXA uses standard escape sequences for control chars", () => {
-        // AppleScript converts to HTML (<br>) for Notes.app
-        // JXA uses standard \n which may need conversion for Notes
-        const input = "line1\nline2";
-        const escaped = escapeForJXA(input);
-        expect(escaped).toBe("line1\\nline2");
-    });
-    it("JXA handles backslashes with standard escaping", () => {
-        // AppleScript needs HTML entity encoding (&#92;) for Notes.app
-        // JXA uses standard \\ escaping
-        const input = "path\\to\\file";
-        const escaped = escapeForJXA(input);
-        expect(escaped).toBe("path\\\\to\\\\file");
-    });
-});

package/build/utils/noteMetadata.js

@@ -1,135 +0,0 @@
-/**
- * Apple Notes Read-Only Metadata Reader [BETA]
- *
- * Reads note metadata that the AppleScript dictionary does not expose (pinned
- * state, checklist flags, trash/recovery, preview snippet, password hint) by
- * querying the NoteStore SQLite database directly.
- *
- * Unlike the note body (a gzipped protobuf blob in ZICNOTEDATA.ZDATA), these are
- * plain scalar columns on ZICCLOUDSYNCINGOBJECT, so no protobuf decoding is
- * needed — an ordinary SELECT is enough.
- *
- * BETA / safety:
- * - The database is opened READ-ONLY (`sqlite3 -readonly`). This code never
- *   writes to the live store; doing so would corrupt CloudKit sync state.
- * - Requires Full Disk Access for the host process.
- * - The schema changes between macOS releases, so the reader feature-detects
- *   which columns exist (PRAGMA table_info) and only selects those.
- *
- * @module utils/noteMetadata
- * @see TECHNICAL_NOTES.md#read-only-metadata-columns-verified-macos-27--notes-413
- */
-import { execFileSync } from "child_process";
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-const NOTES_DB_PATH = path.join(os.homedir(), "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite");
-const FDA_MESSAGE = "Full Disk Access is required to read note metadata. " +
-    "Grant access in System Settings > Privacy & Security > Full Disk Access, " +
-    "then add and restart this application.";
-/**
- * Friendly field name -> NoteStore column. This is a fixed allowlist; nothing
- * here is built from user input, so the column names are never an injection
- * vector. `bool` columns store 0/1; `text` columns store strings.
- */
-const COLUMN_MAP = [
-    { key: "pinned", column: "ZISPINNED", type: "bool" },
-    { key: "hasChecklist", column: "ZHASCHECKLIST", type: "bool" },
-    { key: "hasChecklistInProgress", column: "ZHASCHECKLISTINPROGRESS", type: "bool" },
-    { key: "recoveringFromTrash", column: "ZISRECOVERINGFROMTRASH", type: "bool" },
-    { key: "passwordProtected", column: "ZISPASSWORDPROTECTED", type: "bool" },
-    { key: "passwordHint", column: "ZPASSWORDHINT", type: "text" },
-    { key: "snippet", column: "ZSNIPPET", type: "text" },
-    { key: "widgetSnippet", column: "ZWIDGETSNIPPET", type: "text" },
-    { key: "smartFolderQuery", column: "ZSMARTFOLDERQUERYJSON", type: "text" },
-];
-/**
- * Runs a read-only sqlite3 query against the live NoteStore and returns trimmed
- * stdout. Throws on failure (callers classify the error).
- *
- * Uses execFileSync with an argument array (no shell), so the database path's
- * spaces and the query string are passed verbatim and shell metacharacters are
- * never interpreted. The only dynamic value in any query is the note's primary
- * key, which callers constrain to digits before it reaches here.
- */
-function runSqlite(query) {
-    return execFileSync("sqlite3", ["-readonly", NOTES_DB_PATH, query], {
-        encoding: "utf8",
-        timeout: 5000,
-        stdio: ["pipe", "pipe", "pipe"],
-    }).trim();
-}
-/**
- * Returns the set of column names present on ZICCLOUDSYNCINGOBJECT, so the
- * reader can skip columns that do not exist on this macOS version.
- */
-function presentColumns() {
-    const out = runSqlite("PRAGMA table_info(ZICCLOUDSYNCINGOBJECT);");
-    const cols = new Set();
-    for (const line of out.split("\n")) {
-        // Each row: cid|name|type|notnull|dflt_value|pk
-        const name = line.split("|")[1];
-        if (name)
-            cols.add(name);
-    }
-    return cols;
-}
-/**
- * Reads read-only metadata for a note by its CoreData ID.
- *
- * @param noteId - CoreData URL identifier (e.g., "x-coredata://ABC/ICNote/p123")
- * @returns Structured result with the metadata, an error type, and a message
- */
-export function getNoteMetadata(noteId) {
-    const pkMatch = noteId.match(/\/p(\d+)$/);
-    if (!pkMatch) {
-        return {
-            metadata: null,
-            error: "invalid_id",
-            message: `Invalid note ID format: "${noteId}". Expected format: x-coredata://UUID/ICNote/pNNN`,
-        };
-    }
-    const pk = pkMatch[1];
-    if (!fs.existsSync(NOTES_DB_PATH)) {
-        return { metadata: null, error: "no_fda", message: FDA_MESSAGE };
-    }
-    try {
-        const available = presentColumns();
-        const selected = COLUMN_MAP.filter((c) => available.has(c.column));
-        if (selected.length === 0) {
-            // Schema has none of the known columns (very old or very new macOS).
-            return { metadata: {} };
-        }
-        const pairs = selected.map((c) => `'${c.key}', ${c.column}`).join(", ");
-        const row = runSqlite(`SELECT json_object(${pairs}) FROM ZICCLOUDSYNCINGOBJECT WHERE Z_PK = ${pk};`);
-        if (!row) {
-            return {
-                metadata: null,
-                error: "not_found",
-                message: `No note found in the database for ID "${noteId}".`,
-            };
-        }
-        const raw = JSON.parse(row);
-        const metadata = {};
-        for (const c of selected) {
-            const value = raw[c.key];
-            if (value === null || value === undefined)
-                continue;
-            if (c.type === "bool") {
-                metadata[c.key] = value === 1 || value === "1" || value === true;
-            }
-            else {
-                metadata[c.key] = String(value);
-            }
-        }
-        return { metadata: metadata };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("authorization denied") || message.includes("unable to open database")) {
-            return { metadata: null, error: "no_fda", message: FDA_MESSAGE };
-        }
-        console.error(`Failed to read note metadata: ${message}`);
-        return { metadata: null, error: "query_error", message: "Failed to read note metadata." };
-    }
-}

package/build/utils/noteMetadata.test.js

@@ -1,106 +0,0 @@
-/**
- * Tests for the read-only note metadata reader.
- *
- * The NoteStore SQLite access is mocked, so these exercise the pk extraction,
- * column feature-detection, JSON parsing, boolean coercion, and error
- * classification without touching a real database.
- */
-import { describe, it, expect, vi, beforeEach } from "vitest";
-vi.mock("child_process", () => ({
-    execFileSync: vi.fn(),
-}));
-vi.mock("fs", () => ({
-    existsSync: vi.fn(() => true),
-}));
-import { execFileSync } from "child_process";
-import { existsSync } from "fs";
-import { getNoteMetadata } from "./noteMetadata.js";
-const mockExecFileSync = vi.mocked(execFileSync);
-const mockExistsSync = vi.mocked(existsSync);
-const NOTE_ID = "x-coredata://ABC/ICNote/p123";
-/** Builds a PRAGMA table_info dump from a list of column names. */
-function tableInfo(columns) {
-    return columns.map((name, i) => `${i}|${name}|INTEGER|0||0`).join("\n");
-}
-/** The query string is the third sqlite3 argument: [-readonly, dbPath, query]. */
-function queryOf(call) {
-    const args = call[1];
-    return args[2];
-}
-describe("getNoteMetadata", () => {
-    beforeEach(() => {
-        vi.clearAllMocks();
-        mockExistsSync.mockReturnValue(true);
-    });
-    it("rejects a malformed note id without touching the database", () => {
-        const result = getNoteMetadata("not-a-real-id");
-        expect(result.metadata).toBeNull();
-        expect(result.error).toBe("invalid_id");
-        expect(mockExecFileSync).not.toHaveBeenCalled();
-    });
-    it("reads pinned/checklist/snippet and coerces 0/1 to booleans", () => {
-        mockExecFileSync.mockImplementation((_cmd, args) => {
-            const query = args[2];
-            if (query.includes("table_info")) {
-                return tableInfo(["Z_PK", "ZISPINNED", "ZHASCHECKLIST", "ZSNIPPET", "ZPASSWORDHINT"]);
-            }
-            return JSON.stringify({
-                pinned: 1,
-                hasChecklist: 0,
-                snippet: "Hello world",
-                passwordHint: null,
-            });
-        });
-        const result = getNoteMetadata(NOTE_ID);
-        expect(result.error).toBeUndefined();
-        expect(result.metadata).toEqual({
-            pinned: true,
-            hasChecklist: false,
-            snippet: "Hello world",
-        });
-        // A NULL column (passwordHint) is omitted, not included as null.
-        expect(result.metadata).not.toHaveProperty("passwordHint");
-    });
-    it("only selects columns that exist on this schema", () => {
-        mockExecFileSync.mockImplementation((_cmd, args) => {
-            const query = args[2];
-            if (query.includes("table_info"))
-                return tableInfo(["Z_PK", "ZISPINNED"]);
-            return JSON.stringify({ pinned: 1 });
-        });
-        const result = getNoteMetadata(NOTE_ID);
-        expect(result.metadata).toEqual({ pinned: true });
-        // The SELECT must not reference a column the schema lacks.
-        const selectCall = mockExecFileSync.mock.calls.find((c) => queryOf(c).includes("json_object"));
-        expect(selectCall).toBeDefined();
-        expect(queryOf(selectCall)).toContain("ZISPINNED");
-        expect(queryOf(selectCall)).not.toContain("ZSNIPPET");
-    });
-    it("returns not_found when no row matches the primary key", () => {
-        mockExecFileSync.mockImplementation((_cmd, args) => {
-            const query = args[2];
-            if (query.includes("table_info"))
-                return tableInfo(["Z_PK", "ZISPINNED"]);
-            return "";
-        });
-        const result = getNoteMetadata(NOTE_ID);
-        expect(result.metadata).toBeNull();
-        expect(result.error).toBe("not_found");
-    });
-    it("classifies a Full Disk Access denial", () => {
-        mockExecFileSync.mockImplementation(() => {
-            throw new Error("Error: authorization denied");
-        });
-        const result = getNoteMetadata(NOTE_ID);
-        expect(result.metadata).toBeNull();
-        expect(result.error).toBe("no_fda");
-        expect(result.message).toContain("Full Disk Access");
-    });
-    it("returns no_fda when the database file is missing", () => {
-        mockExistsSync.mockReturnValue(false);
-        const result = getNoteMetadata(NOTE_ID);
-        expect(result.metadata).toBeNull();
-        expect(result.error).toBe("no_fda");
-        expect(mockExecFileSync).not.toHaveBeenCalled();
-    });
-});