apple-notes-mcp 2.5.7 → 2.5.8

package/build/utils/protobuf.js

@@ -1,151 +0,0 @@
-/**
- * Minimal Protobuf Wire Format Decoder
- *
- * Decodes raw protobuf binary data without requiring a .proto schema file.
- * Only implements the subset of wire types needed for reading Apple Notes
- * checklist state from the NoteStore protobuf format.
- *
- * Wire types supported:
- * - 0: Varint (integers, booleans)
- * - 2: Length-delimited (strings, bytes, embedded messages)
- *
- * @module utils/protobuf
- */
-/**
- * Protobuf wire types used in Apple Notes data.
- */
-export const WIRE_TYPE = {
-    VARINT: 0,
-    LENGTH_DELIMITED: 2,
-};
-/**
- * Decodes a varint from the buffer at the given offset.
- *
- * Varints use 7 bits per byte with the high bit as a continuation flag.
- * Supports up to 64-bit values (though we only need small integers).
- *
- * @param buf - The protobuf binary data
- * @param offset - Starting byte position
- * @returns Tuple of [decoded value, new offset after the varint]
- */
-export function decodeVarint(buf, offset) {
-    let result = 0;
-    let shift = 0;
-    let pos = offset;
-    while (pos < buf.length) {
-        const byte = buf[pos];
-        result |= (byte & 0x7f) << shift;
-        pos++;
-        if ((byte & 0x80) === 0) {
-            return [result, pos];
-        }
-        shift += 7;
-        if (shift > 35) {
-            // For our use case (small field numbers, small integers),
-            // values requiring more than 35 bits are unexpected
-            throw new Error(`Varint too long at offset ${offset}`);
-        }
-    }
-    throw new Error(`Unexpected end of buffer reading varint at offset ${offset}`);
-}
-/**
- * Decodes all fields from a protobuf message buffer.
- *
- * Iterates through the buffer, decoding tag-value pairs. Unknown wire types
- * cause parsing to stop (returns fields decoded so far).
- *
- * @param buf - The protobuf binary data
- * @returns Array of decoded fields in order
- */
-export function decodeMessage(buf) {
-    const fields = [];
-    let offset = 0;
-    while (offset < buf.length) {
-        let tag;
-        [tag, offset] = decodeVarint(buf, offset);
-        const fieldNumber = tag >>> 3;
-        const wireType = tag & 0x07;
-        if (wireType === WIRE_TYPE.VARINT) {
-            let value;
-            [value, offset] = decodeVarint(buf, offset);
-            fields.push({ fieldNumber, wireType, value });
-        }
-        else if (wireType === WIRE_TYPE.LENGTH_DELIMITED) {
-            let length;
-            [length, offset] = decodeVarint(buf, offset);
-            if (offset + length > buf.length) {
-                break; // Truncated data, return what we have
-            }
-            const value = buf.slice(offset, offset + length);
-            fields.push({ fieldNumber, wireType, value });
-            offset += length;
-        }
-        else if (wireType === 5) {
-            // 32-bit fixed — skip 4 bytes
-            offset += 4;
-        }
-        else if (wireType === 1) {
-            // 64-bit fixed — skip 8 bytes
-            offset += 8;
-        }
-        else {
-            // Unknown wire type — stop parsing
-            break;
-        }
-    }
-    return fields;
-}
-/**
- * Gets all fields with a specific field number from decoded message fields.
- *
- * @param fields - Decoded protobuf fields
- * @param fieldNumber - The field number to filter for
- * @returns Matching fields
- */
-export function getFields(fields, fieldNumber) {
-    return fields.filter((f) => f.fieldNumber === fieldNumber);
-}
-/**
- * Gets the first field with a specific field number.
- *
- * @param fields - Decoded protobuf fields
- * @param fieldNumber - The field number to find
- * @returns The first matching field, or undefined
- */
-export function getField(fields, fieldNumber) {
-    return fields.find((f) => f.fieldNumber === fieldNumber);
-}
-/**
- * Extracts the varint value from a field, returning undefined if not a varint.
- */
-export function varintValue(field) {
-    if (!field || typeof field.value !== "number")
-        return undefined;
-    return field.value;
-}
-/**
- * Extracts the bytes value from a field, returning undefined if not length-delimited.
- */
-export function bytesValue(field) {
-    if (!field || !(field.value instanceof Uint8Array))
-        return undefined;
-    return field.value;
-}
-/**
- * Decodes a length-delimited field as a UTF-8 string.
- */
-export function stringValue(field) {
-    const bytes = bytesValue(field);
-    if (!bytes)
-        return undefined;
-    return new TextDecoder().decode(bytes);
-}
-/**
- * Decodes a length-delimited field as an embedded message.
- */
-export function embeddedMessage(field) {
-    const bytes = bytesValue(field);
-    if (!bytes)
-        return undefined;
-    return decodeMessage(bytes);
-}

package/build/utils/protobuf.test.js

@@ -1,138 +0,0 @@
-/**
- * Tests for the minimal protobuf wire format decoder.
- */
-import { describe, it, expect } from "vitest";
-import { decodeVarint, decodeMessage, getField, getFields, varintValue, bytesValue, stringValue, embeddedMessage, WIRE_TYPE, } from "./protobuf.js";
-describe("decodeVarint", () => {
-    it("decodes single-byte varint", () => {
-        // 0x08 = field 1, varint; 0x05 = value 5
-        const [value, offset] = decodeVarint(new Uint8Array([5]), 0);
-        expect(value).toBe(5);
-        expect(offset).toBe(1);
-    });
-    it("decodes multi-byte varint", () => {
-        // 300 = 0xAC 0x02
-        const [value, offset] = decodeVarint(new Uint8Array([0xac, 0x02]), 0);
-        expect(value).toBe(300);
-        expect(offset).toBe(2);
-    });
-    it("decodes varint at non-zero offset", () => {
-        const [value, offset] = decodeVarint(new Uint8Array([0xff, 0x03]), 1);
-        expect(value).toBe(3);
-        expect(offset).toBe(2);
-    });
-    it("decodes zero", () => {
-        const [value, offset] = decodeVarint(new Uint8Array([0x00]), 0);
-        expect(value).toBe(0);
-        expect(offset).toBe(1);
-    });
-    it("throws on truncated varint", () => {
-        expect(() => decodeVarint(new Uint8Array([0x80]), 0)).toThrow("Unexpected end of buffer");
-    });
-});
-describe("decodeMessage", () => {
-    it("decodes a message with a varint field", () => {
-        // Field 1, wire type 0 (varint), value 150
-        // Tag: (1 << 3) | 0 = 0x08
-        // Value: 150 = 0x96 0x01
-        const buf = new Uint8Array([0x08, 0x96, 0x01]);
-        const fields = decodeMessage(buf);
-        expect(fields).toHaveLength(1);
-        expect(fields[0].fieldNumber).toBe(1);
-        expect(fields[0].wireType).toBe(WIRE_TYPE.VARINT);
-        expect(fields[0].value).toBe(150);
-    });
-    it("decodes a message with a length-delimited field", () => {
-        // Field 2, wire type 2 (length-delimited), value "hi"
-        // Tag: (2 << 3) | 2 = 0x12
-        // Length: 2
-        // Data: 0x68 0x69 = "hi"
-        const buf = new Uint8Array([0x12, 0x02, 0x68, 0x69]);
-        const fields = decodeMessage(buf);
-        expect(fields).toHaveLength(1);
-        expect(fields[0].fieldNumber).toBe(2);
-        expect(fields[0].wireType).toBe(WIRE_TYPE.LENGTH_DELIMITED);
-        expect(fields[0].value).toBeInstanceOf(Uint8Array);
-        expect(new TextDecoder().decode(fields[0].value)).toBe("hi");
-    });
-    it("decodes multiple fields", () => {
-        // Field 1 varint=1, Field 2 varint=2
-        const buf = new Uint8Array([0x08, 0x01, 0x10, 0x02]);
-        const fields = decodeMessage(buf);
-        expect(fields).toHaveLength(2);
-        expect(fields[0].fieldNumber).toBe(1);
-        expect(fields[0].value).toBe(1);
-        expect(fields[1].fieldNumber).toBe(2);
-        expect(fields[1].value).toBe(2);
-    });
-    it("handles empty buffer", () => {
-        const fields = decodeMessage(new Uint8Array([]));
-        expect(fields).toHaveLength(0);
-    });
-    it("handles truncated length-delimited field gracefully", () => {
-        // Tag for field 2 length-delimited, length=10, but only 2 bytes of data
-        const buf = new Uint8Array([0x12, 0x0a, 0x68, 0x69]);
-        const fields = decodeMessage(buf);
-        // Should stop parsing rather than crash
-        expect(fields).toHaveLength(0);
-    });
-});
-describe("field accessors", () => {
-    // Build a test message with: field 1 = varint 42, field 2 = "hello", field 2 = "world"
-    const buf = new Uint8Array([
-        0x08,
-        0x2a, // field 1, varint, value 42
-        0x12,
-        0x05,
-        0x68,
-        0x65,
-        0x6c,
-        0x6c,
-        0x6f, // field 2, "hello"
-        0x12,
-        0x05,
-        0x77,
-        0x6f,
-        0x72,
-        0x6c,
-        0x64, // field 2, "world"
-    ]);
-    const fields = decodeMessage(buf);
-    it("getField returns first matching field", () => {
-        const f = getField(fields, 2);
-        expect(f).toBeDefined();
-        expect(new TextDecoder().decode(f.value)).toBe("hello");
-    });
-    it("getFields returns all matching fields", () => {
-        const matches = getFields(fields, 2);
-        expect(matches).toHaveLength(2);
-    });
-    it("getField returns undefined for missing field", () => {
-        expect(getField(fields, 99)).toBeUndefined();
-    });
-    it("varintValue extracts number", () => {
-        expect(varintValue(getField(fields, 1))).toBe(42);
-    });
-    it("varintValue returns undefined for non-varint", () => {
-        expect(varintValue(getField(fields, 2))).toBeUndefined();
-    });
-    it("bytesValue extracts Uint8Array", () => {
-        const bytes = bytesValue(getField(fields, 2));
-        expect(bytes).toBeInstanceOf(Uint8Array);
-        expect(bytes.length).toBe(5);
-    });
-    it("stringValue decodes UTF-8", () => {
-        expect(stringValue(getField(fields, 2))).toBe("hello");
-    });
-    it("embeddedMessage decodes nested message", () => {
-        // Create a field 1 containing an embedded message with field 1 = varint 7
-        const inner = new Uint8Array([0x08, 0x07]); // field 1, varint 7
-        // Wrap as field 1, length-delimited
-        const outer = new Uint8Array([0x0a, 0x02, ...inner]);
-        const outerFields = decodeMessage(outer);
-        const nested = embeddedMessage(getField(outerFields, 1));
-        expect(nested).toBeDefined();
-        expect(nested).toHaveLength(1);
-        expect(varintValue(getField(nested, 1))).toBe(7);
-    });
-});

package/build/utils/syncDetection.js

@@ -1,242 +0,0 @@
-/**
- * iCloud Sync Detection Utilities
- *
- * Detects when iCloud sync is in progress or has pending changes,
- * allowing operations to warn users and verify results.
- *
- * Detection methods:
- * 1. Query NoteStore.sqlite for pending sync changes (ZICCLOUDSTATE)
- * 2. Check for recent database transaction activity
- * 3. Monitor WAL file modification time
- *
- * @module utils/syncDetection
- */
-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 WAL_PATH = `${NOTES_DB_PATH}-wal`;
-// How recent (in seconds) activity must be to be considered "active sync"
-const RECENT_ACTIVITY_THRESHOLD_SECONDS = 5;
-// Delay between operation and verification read (ms)
-const VERIFICATION_DELAY_MS = 500;
-// Cache TTL in milliseconds (2 seconds default)
-const SYNC_STATUS_CACHE_TTL_MS = 2000;
-// Cached sync status
-let cachedSyncStatus = null;
-let cacheTimestamp = 0;
-/**
- * Clears the sync status cache.
- * Useful for testing or when forcing a fresh check.
- */
-export function clearSyncStatusCache() {
-    cachedSyncStatus = null;
-    cacheTimestamp = 0;
-}
-/**
- * Gets the current iCloud sync status by querying the Notes database.
- *
- * Results are cached for 2 seconds to avoid excessive database queries
- * during rapid successive operations.
- *
- * @param useCache - Whether to use cached results (default: true)
- * @returns Sync status information
- */
-export function getSyncStatus(useCache = true) {
-    // Return cached result if valid
-    if (useCache && cachedSyncStatus && Date.now() - cacheTimestamp < SYNC_STATUS_CACHE_TTL_MS) {
-        return cachedSyncStatus;
-    }
-    const status = {
-        syncDetected: false,
-        pendingUpload: 0,
-        secondsSinceLastChange: Infinity,
-        recentActivity: false,
-    };
-    try {
-        // Check if database exists
-        if (!fs.existsSync(NOTES_DB_PATH)) {
-            status.error = "Notes database not found";
-            cachedSyncStatus = status;
-            cacheTimestamp = Date.now();
-            return status;
-        }
-        // Check WAL file modification time for recent activity
-        if (fs.existsSync(WAL_PATH)) {
-            const walStats = fs.statSync(WAL_PATH);
-            const secondsAgo = (Date.now() - walStats.mtimeMs) / 1000;
-            status.secondsSinceLastChange = Math.round(secondsAgo);
-            status.recentActivity = secondsAgo < RECENT_ACTIVITY_THRESHOLD_SECONDS;
-        }
-        // Query for pending sync changes
-        // Use a read-only connection and timeout to avoid blocking
-        const query = `
-      SELECT COUNT(*) FROM ZICCLOUDSTATE
-      WHERE ZCURRENTLOCALVERSION > ZLATESTVERSIONSYNCEDTOCLOUD
-      AND ZLATESTVERSIONSYNCEDTOCLOUD IS NOT NULL;
-    `;
-        // Use execFileSync (argv array, no shell) to match the sibling sqlite callers
-        // (checklistParser.ts, noteMetadata.ts). The values here aren't user-controlled,
-        // but argv form avoids shell quoting/interpolation entirely.
-        const result = execFileSync("sqlite3", ["-readonly", NOTES_DB_PATH, query.replace(/\n/g, " ")], {
-            encoding: "utf8",
-            timeout: 5000,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        status.pendingUpload = parseInt(result.trim(), 10) || 0;
-        // Determine if sync is detected
-        status.syncDetected = status.pendingUpload > 0 || status.recentActivity;
-        // Generate warning message
-        if (status.syncDetected) {
-            const reasons = [];
-            if (status.pendingUpload > 0) {
-                reasons.push(`${status.pendingUpload} item(s) pending upload`);
-            }
-            if (status.recentActivity) {
-                reasons.push(`database modified ${status.secondsSinceLastChange}s ago`);
-            }
-            status.warning = `iCloud sync in progress: ${reasons.join(", ")}. Results may be incomplete or change shortly.`;
-        }
-    }
-    catch (error) {
-        // Don't fail the operation due to sync detection errors
-        status.error = error instanceof Error ? error.message : "Failed to check sync status";
-    }
-    // Cache the result
-    cachedSyncStatus = status;
-    cacheTimestamp = Date.now();
-    return status;
-}
-/**
- * Logs a sync warning if sync is detected.
- *
- * @param status - The sync status to check
- * @param operation - Name of the operation being performed
- */
-export function logSyncWarning(status, operation) {
-    if (status.warning) {
-        console.error(`[Sync Warning] ${operation}: ${status.warning}`);
-    }
-}
-/**
- * Wraps an async operation with sync detection and verification.
- *
- * 1. Checks sync status before the operation
- * 2. Logs a warning if sync is detected
- * 3. Executes the operation
- * 4. Waits briefly and checks sync status again
- * 5. Determines if sync may have interfered
- *
- * @param operation - Name of the operation (for logging)
- * @param fn - The async operation to execute
- * @returns Result with sync status information
- */
-export async function withSyncAwareness(operation, fn) {
-    // Check sync status before operation
-    const syncBefore = getSyncStatus();
-    // Log warning if sync detected
-    if (syncBefore.syncDetected) {
-        logSyncWarning(syncBefore, operation);
-    }
-    // Execute the operation
-    const result = await fn();
-    // Wait briefly for any sync activity to settle
-    await new Promise((resolve) => setTimeout(resolve, VERIFICATION_DELAY_MS));
-    // Check sync status after operation (bypass cache for fresh data)
-    const syncAfter = getSyncStatus(false);
-    // Determine if sync may have interfered
-    // Interference is likely if:
-    // 1. Sync was active before and pending count changed
-    // 2. Database was modified during the operation
-    const pendingChanged = syncBefore.pendingUpload !== syncAfter.pendingUpload;
-    const wasRecentBefore = syncBefore.recentActivity;
-    const isRecentAfter = syncAfter.recentActivity;
-    const syncInterference = (syncBefore.syncDetected && pendingChanged) || (wasRecentBefore && isRecentAfter);
-    let interferenceWarning;
-    if (syncInterference) {
-        interferenceWarning =
-            `iCloud sync activity detected during "${operation}". ` +
-                `Pending items: ${syncBefore.pendingUpload} → ${syncAfter.pendingUpload}. ` +
-                `Results may have been affected by sync.`;
-        console.error(`[Sync Interference] ${interferenceWarning}`);
-    }
-    return {
-        result,
-        syncBefore,
-        syncAfter,
-        syncInterference,
-        interferenceWarning,
-    };
-}
-/**
- * Wraps a sync operation with sync detection and verification.
- * Synchronous version for AppleScript operations.
- *
- * @param operation - Name of the operation (for logging)
- * @param fn - The sync operation to execute
- * @returns Result with sync status information
- */
-export function withSyncAwarenessSync(operation, fn) {
-    // Check sync status before operation
-    const syncBefore = getSyncStatus();
-    // Log warning if sync detected
-    if (syncBefore.syncDetected) {
-        logSyncWarning(syncBefore, operation);
-    }
-    // Execute the operation
-    const result = fn();
-    // Check sync status after operation (bypass cache for fresh data)
-    const syncAfter = getSyncStatus(false);
-    // Determine if sync may have interfered
-    const pendingChanged = syncBefore.pendingUpload !== syncAfter.pendingUpload;
-    const wasRecentBefore = syncBefore.recentActivity;
-    const isRecentAfter = syncAfter.recentActivity;
-    const syncInterference = (syncBefore.syncDetected && pendingChanged) || (wasRecentBefore && isRecentAfter);
-    let interferenceWarning;
-    if (syncInterference) {
-        interferenceWarning =
-            `iCloud sync activity detected during "${operation}". ` +
-                `Pending items: ${syncBefore.pendingUpload} → ${syncAfter.pendingUpload}. ` +
-                `Results may have been affected by sync.`;
-        console.error(`[Sync Interference] ${interferenceWarning}`);
-    }
-    return {
-        result,
-        syncBefore,
-        syncAfter,
-        syncInterference,
-        interferenceWarning,
-    };
-}
-/**
- * Checks if sync is currently active.
- * Convenience method for simple sync checks.
- *
- * @returns true if sync activity is detected
- */
-export function isSyncActive() {
-    return getSyncStatus().syncDetected;
-}
-/**
- * Gets a human-readable sync status summary.
- *
- * @returns Status summary string
- */
-export function getSyncStatusSummary() {
-    const status = getSyncStatus();
-    if (status.error) {
-        return `Sync status unknown: ${status.error}`;
-    }
-    if (!status.syncDetected) {
-        return "iCloud sync: Idle";
-    }
-    const parts = ["iCloud sync: Active"];
-    if (status.pendingUpload > 0) {
-        parts.push(`${status.pendingUpload} pending upload(s)`);
-    }
-    if (status.recentActivity) {
-        parts.push(`last activity ${status.secondsSinceLastChange}s ago`);
-    }
-    return parts.join(" - ");
-}