apple-notes-mcp 1.2.18 → 1.2.19

package/build/services/appleNotesManager.test.js

@@ -17,8 +17,14 @@ import { AppleNotesManager, escapeForAppleScript, escapeHtmlForAppleScript, pars
 vi.mock("@/utils/applescript.js", () => ({
     executeAppleScript: vi.fn(),
 }));
+// Mock the checklist parser to avoid SQLite access during tests
+vi.mock("@/utils/checklistParser.js", () => ({
+    getChecklistItems: vi.fn().mockReturnValue({ items: null }),
+}));
 import { executeAppleScript } from "../utils/applescript.js";
 const mockExecuteAppleScript = vi.mocked(executeAppleScript);
+import { getChecklistItems } from "../utils/checklistParser.js";
+const mockGetChecklistItems = vi.mocked(getChecklistItems);
 // =============================================================================
 // Text Escaping Tests
 // =============================================================================
@@ -261,6 +267,37 @@ describe("AppleNotesManager", () => {
             const result = manager.createNote("Tagged Note", "Content", ["work", "urgent"]);
             expect(result?.tags).toEqual(["work", "urgent"]);
         });
+        it("uses escapeHtmlForAppleScript when format is html", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "note id x-coredata://12345/ICNote/p200",
+            });
+            const htmlContent = "<h2>Heading</h2><div>Body text</div>";
+            const result = manager.createNote("HTML Note", htmlContent, [], undefined, undefined, "html");
+            expect(result).not.toBeNull();
+            // HTML tags should NOT be entity-encoded — they should pass through to AppleScript
+            // escapeHtmlForAppleScript only escapes \ and ", not HTML tags
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("<h2>Heading</h2><div>Body text</div>"));
+        });
+        it("uses escapeForAppleScript when format is plaintext (default)", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "note id x-coredata://12345/ICNote/p201",
+            });
+            const result = manager.createNote("Plain Note", "Simple text with\nnewline");
+            expect(result).not.toBeNull();
+            // Default plaintext: newlines become <br>
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("Simple text with<br>newline"));
+        });
+        it("escapes double quotes in html format for AppleScript safety", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "note id x-coredata://12345/ICNote/p202",
+            });
+            manager.createNote("Quote Test", '<div class="test">Content</div>', [], undefined, undefined, "html");
+            // Double quotes must be escaped for AppleScript string embedding
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('<div class=\\"test\\">Content</div>'));
+        });
     });
     // ---------------------------------------------------------------------------
     // Note Search
@@ -606,6 +643,67 @@ describe("AppleNotesManager", () => {
             manager.updateNote("Old Title", "Brand New Title", "Content");
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("<div>Brand New Title</div>"));
         });
+        it("uses HTML content directly when format is html", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "",
+            });
+            // Use content with &amp; — if escapeForAppleScript were accidentally used,
+            // the & in &amp; would become &amp;amp;, causing this assertion to fail.
+            const htmlContent = "<h1>Title</h1><div>A &amp; B</div>";
+            const result = manager.updateNote("Old Title", undefined, htmlContent, undefined, "html");
+            expect(result).toBe(true);
+            // In HTML mode: content is used as-is, no <div> wrapper added
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining(`to "${htmlContent}"`));
+        });
+        it("does not wrap HTML content in div tags when format is html", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "",
+            });
+            manager.updateNote("Old Title", undefined, "<h1>My Title</h1><div>Content</div>", undefined, "html");
+            // Should NOT contain the <div>Old Title</div> wrapper
+            expect(mockExecuteAppleScript).not.toHaveBeenCalledWith(expect.stringContaining("<div>Old Title</div>"));
+        });
+        it("still wraps in div tags when format is plaintext (default)", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "",
+            });
+            manager.updateNote("My Title", undefined, "Plain content");
+            // Default behavior: should have <div> wrapper
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining("<div>My Title</div><div>Plain content</div>"));
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Note Update by ID
+    // ---------------------------------------------------------------------------
+    describe("updateNoteById", () => {
+        it("uses HTML content directly without div wrapping in HTML mode", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "",
+            });
+            const htmlContent = "<h1>My Title</h1><div>A &amp; B</div>";
+            const result = manager.updateNoteById("x-coredata://abc/123", undefined, htmlContent, "html");
+            expect(result).toBe(true);
+            // HTML mode: content passed directly, no <div> wrapper
+            expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining(`to "${htmlContent}"`));
+            // Should NOT contain the div-wrapped title pattern
+            expect(mockExecuteAppleScript).not.toHaveBeenCalledWith(expect.stringContaining("<div>My Title</div>"));
+        });
+        it("does not call getNoteById in HTML mode (skips lookup optimization)", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: "",
+            });
+            const htmlContent = "<h1>Title</h1><div>Body</div>";
+            manager.updateNoteById("x-coredata://abc/456", undefined, htmlContent, "html");
+            // In HTML mode, getNoteById should NOT be called (it would trigger
+            // an additional executeAppleScript call). Only one call should happen:
+            // the update itself.
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1);
+        });
     });
     // ---------------------------------------------------------------------------
     // Note Listing
@@ -1242,5 +1340,38 @@ describe("AppleNotesManager", () => {
             const markdown = manager.getNoteMarkdownById("x-coredata://invalid");
             expect(markdown).toBe("");
         });
+        it("enriches markdown with checklist state when available", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
+                success: true,
+                output: "<ul><li>Buy milk</li><li>Walk dog</li><li>Send email</li></ul>",
+            });
+            mockGetChecklistItems.mockReturnValueOnce({
+                items: [
+                    { text: "Buy milk", done: true },
+                    { text: "Walk dog", done: false },
+                    { text: "Send email", done: true },
+                ],
+            });
+            const markdown = manager.getNoteMarkdownById("x-coredata://ABC/ICNote/p123");
+            expect(markdown).toMatch(/-\s+\[x\] Buy milk/);
+            expect(markdown).toMatch(/-\s+\[ \] Walk dog/);
+            expect(markdown).toMatch(/-\s+\[x\] Send email/);
+        });
+        it("returns plain markdown when checklist state is unavailable", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
+                success: true,
+                output: "<ul><li>Item 1</li><li>Item 2</li></ul>",
+            });
+            mockGetChecklistItems.mockReturnValueOnce({
+                items: null,
+                error: "no_fda",
+                message: "Full Disk Access required",
+            });
+            const markdown = manager.getNoteMarkdownById("x-coredata://ABC/ICNote/p456");
+            expect(markdown).toMatch(/-\s+Item 1/);
+            expect(markdown).toMatch(/-\s+Item 2/);
+            expect(markdown).not.toContain("[x]");
+            expect(markdown).not.toContain("[ ]");
+        });
     });
 });

package/build/utils/checklistParser.js

@@ -0,0 +1,259 @@
+/**
+ * Apple Notes Checklist State Parser
+ *
+ * Reads checklist done/undone state by querying the NoteStore SQLite database
+ * and decoding the protobuf-encoded note content. This bypasses the AppleScript
+ * limitation where `body of note` strips checklist state information.
+ *
+ * Data flow:
+ * 1. Query NoteStore.sqlite for the gzipped protobuf blob (ZICNOTEDATA.ZDATA)
+ * 2. Decompress with gzip
+ * 3. Decode protobuf to extract text and attribute runs
+ * 4. Walk attribute runs to identify checklist items and their done state
+ *
+ * Protobuf field path:
+ *   Document (root) → field 2 (Note) → field 3 (Note body)
+ *     → field 2 (note_text: plain text)
+ *     → field 5 (attribute_run: repeated styling runs)
+ *       → field 1 (length)
+ *       → field 2 (paragraph_style)
+ *         → field 1 (style_type: 103 = checklist)
+ *         → field 5 (checklist)
+ *           → field 2 (done: 0 = unchecked, 1 = checked)
+ *
+ * @module utils/checklistParser
+ * @see https://github.com/sweetrb/apple-notes-mcp/issues/2
+ */
+import { execSync } from "child_process";
+import * as zlib from "zlib";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { decodeMessage, getField, getFields, varintValue, stringValue, embeddedMessage, } from "../utils/protobuf.js";
+/** Style type value for checklist items in Apple Notes protobuf format. */
+const CHECKLIST_STYLE_TYPE = 103;
+const NOTES_DB_PATH = path.join(os.homedir(), "Library/Group Containers/group.com.apple.notes/NoteStore.sqlite");
+/**
+ * Checks whether the NoteStore database is accessible (Full Disk Access).
+ *
+ * @returns true if the database file exists and can be read
+ */
+export function hasFullDiskAccess() {
+    try {
+        if (!fs.existsSync(NOTES_DB_PATH))
+            return false;
+        // Try to open the database with a simple query
+        execSync(`sqlite3 -readonly "${NOTES_DB_PATH}" "SELECT 1;"`, {
+            encoding: "utf8",
+            timeout: 3000,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Queries the NoteStore SQLite database for a note's raw ZDATA blob.
+ *
+ * Uses the note's CoreData identifier to find the corresponding protobuf data.
+ * The identifier is extracted from the full CoreData URL format:
+ *   x-coredata://DEVICE-UUID/ICNote/pXXXX → pXXXX
+ *
+ * @param noteId - CoreData URL identifier (e.g., "x-coredata://ABC/ICNote/p123")
+ * @returns Object with hex data or error classification
+ */
+function queryNoteData(noteId) {
+    // Extract the primary key suffix (e.g., "p123" from "x-coredata://ABC/ICNote/p123")
+    const pkMatch = noteId.match(/\/p(\d+)$/);
+    if (!pkMatch) {
+        console.error(`Invalid note ID format: ${noteId}`);
+        return { hex: null, error: "invalid_id" };
+    }
+    const pk = pkMatch[1];
+    // Query for the gzipped protobuf data, output as hex for safe transport
+    const query = `SELECT hex(nd.ZDATA) FROM ZICNOTEDATA nd JOIN ZICCLOUDSYNCINGOBJECT n ON nd.ZNOTE = n.Z_PK WHERE n.Z_PK = ${pk};`;
+    try {
+        const result = execSync(`sqlite3 -readonly "${NOTES_DB_PATH}" "${query}"`, {
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const hex = result.trim();
+        if (!hex)
+            return { hex: null };
+        return { hex };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to query NoteStore database: ${message}`);
+        // Detect Full Disk Access denial
+        if (message.includes("authorization denied") || message.includes("unable to open database")) {
+            return { hex: null, error: "no_fda" };
+        }
+        return { hex: null };
+    }
+}
+/**
+ * Converts a hex string to a Uint8Array.
+ */
+function hexToBytes(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Extracts checklist items from a protobuf-encoded note.
+ *
+ * Navigates the protobuf structure:
+ *   Document → Note (field 2) → Note body (field 3)
+ *     → note_text (field 2): plain text with \n line separators
+ *     → attribute_run (field 5): repeated, sequential styling runs
+ *
+ * Walks attribute runs sequentially, tracking character position in the plain
+ * text. When a run has style_type == 103 (checklist), extracts the line text
+ * and done state.
+ *
+ * @param data - Decompressed protobuf bytes
+ * @returns Array of checklist items, or null if parsing fails
+ */
+function parseChecklistFromProtobuf(data) {
+    try {
+        // Document root
+        const docFields = decodeMessage(data);
+        // Field 2 = Note (Version/Document wrapper)
+        const noteWrapper = getField(docFields, 2);
+        const noteWrapperFields = embeddedMessage(noteWrapper);
+        if (!noteWrapperFields)
+            return null;
+        // Field 3 = Note body (the actual content)
+        const noteBody = getField(noteWrapperFields, 3);
+        const noteBodyFields = embeddedMessage(noteBody);
+        if (!noteBodyFields)
+            return null;
+        // Field 2 = note_text (plain text content)
+        const noteTextField = getField(noteBodyFields, 2);
+        const noteText = stringValue(noteTextField);
+        if (!noteText)
+            return null;
+        // Field 5 = attribute_run (repeated)
+        const attributeRuns = getFields(noteBodyFields, 5);
+        if (attributeRuns.length === 0)
+            return null;
+        // Split text into lines for mapping
+        const lines = noteText.split("\n");
+        // Walk attribute runs, tracking position in the text
+        const items = [];
+        let charPos = 0;
+        // Track which lines we've already added (multiple runs can cover the same line)
+        const seenLines = new Set();
+        for (const run of attributeRuns) {
+            const runFields = embeddedMessage(run);
+            if (!runFields)
+                continue;
+            // Field 1 = length (character count this run covers)
+            const lengthField = getField(runFields, 1);
+            const runLength = varintValue(lengthField) ?? 0;
+            // Field 2 = paragraph_style
+            const paragraphStyle = getField(runFields, 2);
+            const styleFields = embeddedMessage(paragraphStyle);
+            if (styleFields) {
+                // Field 1 = style_type
+                const styleType = varintValue(getField(styleFields, 1));
+                if (styleType === CHECKLIST_STYLE_TYPE) {
+                    // Field 5 = checklist info
+                    const checklistField = getField(styleFields, 5);
+                    const checklistFields = embeddedMessage(checklistField);
+                    // Field 2 = done (0 = unchecked, 1 = checked)
+                    const done = checklistFields ? (varintValue(getField(checklistFields, 2)) ?? 0) : 0;
+                    // Find which line this position corresponds to
+                    let lineStart = 0;
+                    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+                        const lineEnd = lineStart + lines[lineIdx].length;
+                        if (charPos >= lineStart && charPos < lineEnd + 1 && !seenLines.has(lineIdx)) {
+                            seenLines.add(lineIdx);
+                            items.push({
+                                text: lines[lineIdx],
+                                done: done === 1,
+                            });
+                            break;
+                        }
+                        lineStart = lineEnd + 1; // +1 for the \n
+                    }
+                }
+            }
+            charPos += runLength;
+        }
+        return items;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to parse protobuf checklist data: ${message}`);
+        return null;
+    }
+}
+/**
+ * Gets the checklist state for a note by its CoreData ID.
+ *
+ * This reads directly from the NoteStore SQLite database, bypassing
+ * AppleScript's limitation of stripping checklist state from `body of note`.
+ *
+ * Requires Full Disk Access to read the Notes database.
+ *
+ * @param noteId - CoreData URL identifier (e.g., "x-coredata://ABC/ICNote/p123")
+ * @returns Structured result with items, error type, and message
+ */
+export function getChecklistItems(noteId) {
+    // Query the database for raw note data
+    const { hex: hexData, error: queryError } = queryNoteData(noteId);
+    if (queryError === "invalid_id") {
+        return {
+            items: null,
+            error: "invalid_id",
+            message: `Invalid note ID format: "${noteId}". Expected format: x-coredata://UUID/ICNote/pNNN`,
+        };
+    }
+    if (queryError === "no_fda") {
+        return {
+            items: null,
+            error: "no_fda",
+            message: "Full Disk Access is required to read checklist state. " +
+                "Grant access in System Settings > Privacy & Security > Full Disk Access, " +
+                "then add and restart this application.",
+        };
+    }
+    if (!hexData) {
+        return {
+            items: null,
+            error: "no_checklists",
+            message: "No data found for this note in the database.",
+        };
+    }
+    // Convert hex to bytes and decompress
+    const compressedData = hexToBytes(hexData);
+    let decompressed;
+    try {
+        decompressed = zlib.gunzipSync(compressedData);
+    }
+    catch {
+        console.error("Failed to decompress note data — may not be gzip format");
+        return {
+            items: null,
+            error: "parse_error",
+            message: "Failed to decompress note data.",
+        };
+    }
+    // Parse protobuf and extract checklist items
+    const items = parseChecklistFromProtobuf(new Uint8Array(decompressed));
+    if (!items || items.length === 0) {
+        return {
+            items: null,
+            error: "no_checklists",
+            message: "This note does not contain any checklist items.",
+        };
+    }
+    return { items };
+}

package/build/utils/checklistParser.test.js

@@ -0,0 +1,230 @@
+/**
+ * Tests for the Apple Notes checklist state parser.
+ *
+ * These tests mock the SQLite database access and test the protobuf
+ * parsing logic with realistic test fixtures.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import * as zlib from "zlib";
+import { getChecklistItems, hasFullDiskAccess } from "./checklistParser.js";
+// Mock child_process to avoid actual database access
+vi.mock("child_process", () => ({
+    execSync: vi.fn(),
+    spawnSync: vi.fn(() => ({ error: null })),
+}));
+// Mock fs for database existence checks
+vi.mock("fs", () => ({
+    existsSync: vi.fn(() => true),
+    statSync: vi.fn(() => ({ mtimeMs: Date.now() })),
+}));
+import { execSync } from "child_process";
+import { existsSync } from "fs";
+const mockExecSync = vi.mocked(execSync);
+const mockExistsSync = vi.mocked(existsSync);
+/**
+ * Builds a minimal Apple Notes protobuf structure with checklist items.
+ *
+ * Structure:
+ *   Document (root)
+ *     field 2 (Note wrapper)
+ *       field 3 (Note body)
+ *         field 2 (note_text: plain text)
+ *         field 5 (attribute_run) - repeated
+ */
+function buildChecklistProtobuf(items) {
+    // Helper to encode a varint
+    function encodeVarint(value) {
+        const bytes = [];
+        while (value > 0x7f) {
+            bytes.push((value & 0x7f) | 0x80);
+            value >>>= 7;
+        }
+        bytes.push(value & 0x7f);
+        return bytes;
+    }
+    // Helper to encode a tag
+    function encodeTag(fieldNumber, wireType) {
+        return encodeVarint((fieldNumber << 3) | wireType);
+    }
+    // Helper to wrap bytes as a length-delimited field
+    function lengthDelimited(fieldNumber, data) {
+        const bytes = data instanceof Uint8Array ? Array.from(data) : data;
+        return [...encodeTag(fieldNumber, 2), ...encodeVarint(bytes.length), ...bytes];
+    }
+    // Helper to encode a varint field
+    function varintField(fieldNumber, value) {
+        return [...encodeTag(fieldNumber, 0), ...encodeVarint(value)];
+    }
+    // Build the plain text: "Title\nitem1\nitem2\n..."
+    const textLines = ["Checklist Note", ...items.map((i) => i.text)];
+    const noteText = textLines.join("\n");
+    const encoder = new TextEncoder();
+    // Build attribute runs
+    // First run: title line (not a checklist)
+    const titleLength = textLines[0].length + 1; // +1 for \n
+    const titleRun = lengthDelimited(5, [
+        ...varintField(1, titleLength), // length
+        // No paragraph_style with checklist — just a regular paragraph
+    ]);
+    // Checklist runs
+    const checklistRuns = [];
+    for (const item of items) {
+        const runLength = item.text.length + 1; // +1 for \n (or end of text)
+        // Build checklist info: field 2 = done
+        const checklistInfo = lengthDelimited(5, varintField(2, item.done ? 1 : 0));
+        // Build paragraph_style: field 1 = 103 (checklist), field 5 = checklist info
+        const paragraphStyle = lengthDelimited(2, [...varintField(1, 103), ...checklistInfo]);
+        // Build attribute run: field 1 = length, field 2 = paragraph_style
+        const run = lengthDelimited(5, [...varintField(1, runLength), ...paragraphStyle]);
+        checklistRuns.push(...run);
+    }
+    // Build note body (field 3):
+    //   field 2 = note_text, field 5 = attribute_runs (already encoded above)
+    const noteTextField = lengthDelimited(2, encoder.encode(noteText));
+    const noteBody = lengthDelimited(3, [...noteTextField, ...titleRun, ...checklistRuns]);
+    // Build note wrapper (field 2 of document)
+    const noteWrapper = lengthDelimited(2, noteBody);
+    return new Uint8Array(noteWrapper);
+}
+describe("hasFullDiskAccess", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it("returns true when database is accessible", () => {
+        mockExistsSync.mockReturnValue(true);
+        mockExecSync.mockReturnValue("1\n");
+        expect(hasFullDiskAccess()).toBe(true);
+    });
+    it("returns false when database file does not exist", () => {
+        mockExistsSync.mockReturnValue(false);
+        expect(hasFullDiskAccess()).toBe(false);
+    });
+    it("returns false when sqlite3 query fails", () => {
+        mockExistsSync.mockReturnValue(true);
+        mockExecSync.mockImplementation(() => {
+            throw new Error("authorization denied");
+        });
+        expect(hasFullDiskAccess()).toBe(false);
+    });
+});
+describe("getChecklistItems", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it("returns error for invalid note ID format", () => {
+        const result = getChecklistItems("invalid-id");
+        expect(result.items).toBeNull();
+        expect(result.error).toBe("invalid_id");
+    });
+    it("returns no_checklists when database query returns empty", () => {
+        mockExecSync.mockReturnValue("");
+        const result = getChecklistItems("x-coredata://ABC/ICNote/p123");
+        expect(result.items).toBeNull();
+        expect(result.error).toBe("no_checklists");
+    });
+    it("parses checklist with mixed done/undone items", () => {
+        const items = [
+            { text: "Buy milk", done: true },
+            { text: "Walk dog", done: false },
+            { text: "Send email", done: true },
+        ];
+        const protobuf = buildChecklistProtobuf(items);
+        const compressed = zlib.gzipSync(Buffer.from(protobuf));
+        const hex = Buffer.from(compressed).toString("hex").toUpperCase();
+        mockExecSync.mockReturnValue((hex + "\n"));
+        const result = getChecklistItems("x-coredata://ABC/ICNote/p123");
+        expect(result.items).not.toBeNull();
+        expect(result.items).toHaveLength(3);
+        expect(result.items[0]).toEqual({ text: "Buy milk", done: true });
+        expect(result.items[1]).toEqual({ text: "Walk dog", done: false });
+        expect(result.items[2]).toEqual({ text: "Send email", done: true });
+        expect(result.error).toBeUndefined();
+    });
+    it("parses checklist with all items unchecked", () => {
+        const items = [
+            { text: "Task A", done: false },
+            { text: "Task B", done: false },
+        ];
+        const protobuf = buildChecklistProtobuf(items);
+        const compressed = zlib.gzipSync(Buffer.from(protobuf));
+        const hex = Buffer.from(compressed).toString("hex").toUpperCase();
+        mockExecSync.mockReturnValue((hex + "\n"));
+        const result = getChecklistItems("x-coredata://ABC/ICNote/p456");
+        expect(result.items).not.toBeNull();
+        expect(result.items).toHaveLength(2);
+        expect(result.items.every((i) => !i.done)).toBe(true);
+    });
+    it("parses checklist with all items checked", () => {
+        const items = [
+            { text: "Done 1", done: true },
+            { text: "Done 2", done: true },
+        ];
+        const protobuf = buildChecklistProtobuf(items);
+        const compressed = zlib.gzipSync(Buffer.from(protobuf));
+        const hex = Buffer.from(compressed).toString("hex").toUpperCase();
+        mockExecSync.mockReturnValue((hex + "\n"));
+        const result = getChecklistItems("x-coredata://ABC/ICNote/p789");
+        expect(result.items).not.toBeNull();
+        expect(result.items).toHaveLength(2);
+        expect(result.items.every((i) => i.done)).toBe(true);
+    });
+    it("returns null when note has no checklist items", () => {
+        // Build a protobuf with no checklist style_type
+        const encoder = new TextEncoder();
+        // Minimal note with just text, no checklist runs
+        // Field 2 (note text) = "Just a regular note"
+        const noteText = encoder.encode("Just a regular note");
+        const noteTextField = [0x12, noteText.length, ...noteText]; // field 2, length-delimited
+        // A non-checklist attribute run (style_type = 0, regular paragraph)
+        const regularRun = [
+            0x2a, // field 5, length-delimited (attribute_run)
+            0x04, // length 4
+            0x08,
+            0x13, // field 1 (length) = 19
+            0x12,
+            0x00, // field 2 (paragraph_style) = empty
+        ];
+        const noteBody = [
+            0x1a, // field 3, length-delimited
+            noteTextField.length + regularRun.length,
+            ...noteTextField,
+            ...regularRun,
+        ];
+        const noteWrapper = [0x12, noteBody.length, ...noteBody]; // field 2
+        const compressed = zlib.gzipSync(Buffer.from(new Uint8Array(noteWrapper)));
+        const hex = Buffer.from(compressed).toString("hex").toUpperCase();
+        mockExecSync.mockReturnValue((hex + "\n"));
+        const result = getChecklistItems("x-coredata://ABC/ICNote/p100");
+        expect(result.items).toBeNull();
+        expect(result.error).toBe("no_checklists");
+    });
+    it("returns null when sqlite3 command fails", () => {
+        mockExecSync.mockImplementation(() => {
+            throw new Error("database is locked");
+        });
+        const result = getChecklistItems("x-coredata://ABC/ICNote/p123");
+        expect(result.items).toBeNull();
+    });
+    it("returns no_fda error when authorization is denied", () => {
+        mockExecSync.mockImplementation(() => {
+            throw new Error("unable to open database: authorization denied");
+        });
+        const result = getChecklistItems("x-coredata://ABC/ICNote/p123");
+        expect(result.items).toBeNull();
+        expect(result.error).toBe("no_fda");
+        expect(result.message).toContain("Full Disk Access");
+        expect(result.message).toContain("System Settings");
+    });
+    it("returns parse_error for non-gzip data", () => {
+        // Return valid hex that isn't gzip
+        mockExecSync.mockReturnValue("DEADBEEF\n");
+        const result = getChecklistItems("x-coredata://ABC/ICNote/p123");
+        expect(result.items).toBeNull();
+        expect(result.error).toBe("parse_error");
+    });
+    it("extracts correct primary key from note ID", () => {
+        mockExecSync.mockReturnValue("");
+        getChecklistItems("x-coredata://12345-ABCDE/ICNote/p42");
+        expect(mockExecSync).toHaveBeenCalledWith(expect.stringContaining("Z_PK = 42"), expect.any(Object));
+    });
+});