@mgcrea/mcp-apple-notes 0.0.0-bootstrap

package/dist/server-HLS_dM7r.js

@@ -0,0 +1,1550 @@
+import { AppBusyError as NotesBusyError, AppNotRunningError as NotesNotRunningError, AppleAutomationError, AppleAutomationError as AppleNotesError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, PreconditionError, SchemaDriftError, columnsOf, confirmArg, createOsascriptRunner, describeStore, escapeLike, fingerprintSchema, limitArg, ok, okText, openReadOnly, parseBool, parseConfig, parseIntOpt, parseList, readPackageIdentity, trimmed, withBusyRetry, wrap, wrapResult } from "@mgcrea/mcp-apple-core";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { gunzipSync } from "node:zlib";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+//#region src/build-info.ts
+const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
+	name: "@mgcrea/mcp-apple-notes",
+	version: "0.0.0"
+});
+const BUILD_INFO = {
+	name: pkg.name,
+	version: pkg.version,
+	gitCommit: "df06e7f",
+	gitCommitDate: "2026-08-22T16:20:23+02:00"
+};
+//#endregion
+//#region src/client/errors.ts
+/**
+* Notes' error surface. The taxonomy lives in `@mgcrea/mcp-apple-core`; what
+* belongs here is the identity those messages are written against, and the
+* errors that are genuinely about notes.
+*/
+/** Named in every user-facing error and in the env vars they mention. */
+const NOTES_SURFACE = {
+	appName: "Notes",
+	envPrefix: "APPLE_NOTES"
+};
+/** A NoteRef no longer resolves — the note was deleted, or the index is stale. */
+var NoteNotFoundError = class extends AppleAutomationError {
+	name = "NoteNotFoundError";
+	constructor(ref) {
+		super(`No note for ref "${ref}". It was probably deleted since the search ran. Re-run the search to get a current ref.`);
+	}
+};
+/**
+* The note is password-protected and Notes will not hand over its text.
+*
+* The file lane cannot help either: locked notes are AES ciphertext at rest,
+* which is why `ZICNOTEDATA` carries `ZCRYPTOINITIALIZATIONVECTOR` and
+* `ZCRYPTOTAG` columns. Saying so is more useful than an empty body.
+*/
+var NoteLockedError = class extends AppleAutomationError {
+	name = "NoteLockedError";
+	constructor(ref) {
+		super(`Note "${ref}" is password-protected. Unlock it in Notes and retry — its text is encrypted at rest, so no amount of permission makes it readable from here.`);
+	}
+};
+//#endregion
+//#region src/client/locate.ts
+/**
+* Find Notes' store.
+*
+* Simpler than Mail's, and measurably so: Mail's root is version-numbered
+* (`~/Library/Mail/V10`) *and* TCC-hidden, so it needs a four-branch strategy
+* ladder that asks Mail to name its own directory. Notes has one constant path,
+* confirmed on macOS 26.6.
+*
+* The path is TCC-protected, so `statSync` succeeds on it while `open` and
+* `access` are denied — existence and readability are different questions, and
+* only readability answers whether Full Disk Access is granted.
+*/
+/** `~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite`. */
+const GROUP_CONTAINER = "group.com.apple.notes";
+const defaultStorePath = (home = homedir()) => join(home, "Library", "Group Containers", GROUP_CONTAINER, "NoteStore.sqlite");
+const locateStore = (opts = {}) => {
+	const storePath = opts.storePath ?? defaultStorePath(opts.home);
+	const facts = describeStore(storePath);
+	const reason = facts.exists ? facts.readable ? null : "NoteStore.sqlite exists but cannot be read. Grant Full Disk Access to the app running this server (System Settings > Privacy & Security > Full Disk Access) and restart it. Granting it to Notes.app does nothing — the reader needs the permission." : `No NoteStore.sqlite at ${storePath}. Has Notes ever been set up on this account?`;
+	return {
+		...facts,
+		storePath,
+		mediaRoot: join(dirname(storePath), "Accounts"),
+		reason
+	};
+};
+//#endregion
+//#region src/client/jxa/core.ts
+/**
+* JXA script fragments.
+*
+* Every script here is a static constant. None of them may contain a template
+* interpolation — `assertStaticScript` rejects any script containing `${`, and
+* that includes JavaScript template literals written *inside* the JXA source.
+* Use string concatenation in JXA code.
+*
+* Every script follows the same contract:
+*   - it reads its parameters from `JSON.parse(argv[0])`
+*   - it returns `JSON.stringify({ok: true, data})` on success
+*   - it returns `JSON.stringify({ok: false, error: {code, message}})` on an
+*     application-level failure, still exiting 0
+* so that a non-zero exit always means infrastructure rather than "no such note".
+*
+* ## Two rules the measurements impose
+*
+* 1. **Never read a property per note in a loop.** One note's `plaintext` costs
+*    ~116ms, so a 921-note library would take ~107 seconds. Every read here is a
+*    bulk array fetch (`N.notes.plaintext()`), which is one Apple Event whatever
+*    the size.
+* 2. **Never use `whose` for text search.** `notes.whose({plaintext: ...})` took
+*    671ms against 97ms for pulling everything and filtering in JS — 6.9x slower,
+*    because the specifier evaluates per note across the Apple Event bridge while
+*    the bulk form is a single round trip.
+*/
+/**
+* Shared prelude.
+*
+* The liveness gate matters more than it looks. `Application("Notes").notes`
+* *launches* Notes if it isn't running — which steals focus as a side effect of
+* a read. `NSRunningApplication` answers the same question without launching
+* anything and without a second TCC prompt.
+*
+* Deliberately NOT shared with Mail's prelude: 45% of that file is a UI-scripting
+* workaround for Mail's forced blockquote citation, which every script there
+* carries whether it composes mail or lists accounts. Notes needs none of it.
+*/
+const PRELUDE = `
+ObjC.import("AppKit");
+
+function isNotesRunning() {
+  var apps = $.NSRunningApplication.runningApplicationsWithBundleIdentifier("com.apple.Notes");
+  return apps.count > 0;
+}
+
+function ok(data) { return JSON.stringify({ ok: true, data: data }); }
+function err(code, message) { return JSON.stringify({ ok: false, error: { code: code, message: String(message) } }); }
+
+function iso(d) {
+  try { return d ? d.toISOString() : null; } catch (e) { return null; }
+}
+
+/** Read one property defensively: Notes throws on properties it cannot supply. */
+function prop(fn, fallback) {
+  try {
+    var v = fn();
+    return v === undefined ? fallback : v;
+  } catch (e) {
+    return fallback;
+  }
+}
+
+/**
+ * Zip parallel bulk arrays into records.
+ *
+ * Bulk fetches are the only affordable read shape, and they come back as
+ * separate arrays that line up by index. Rebuilding records here keeps that
+ * assumption in one place.
+ */
+function zip(keys, columns, count) {
+  var out = [];
+  for (var i = 0; i < count; i++) {
+    var row = {};
+    for (var k = 0; k < keys.length; k++) {
+      var col = columns[k];
+      row[keys[k]] = col && i < col.length ? col[i] : null;
+    }
+    out.push(row);
+  }
+  return out;
+}
+
+/** Walk the folder tree. Folders nest in the dictionary, so this recurses. */
+function folderTree(container, accountId, depth, out) {
+  if (depth > 8) return out;
+  var subs = [];
+  try { subs = container.folders(); } catch (e) { return out; }
+  for (var i = 0; i < subs.length; i++) {
+    var f = subs[i];
+    var id = prop(function () { return String(f.id()); }, null);
+    out.push({
+      id: id,
+      name: prop(function () { return String(f.name()); }, null),
+      accountId: accountId,
+      depth: depth,
+      shared: prop(function () { return f.shared(); }, false),
+      noteCount: prop(function () { return f.notes().length; }, null)
+    });
+    folderTree(f, accountId, depth + 1, out);
+  }
+  return out;
+}
+`;
+/**
+* Wrap a script body in the prelude and the liveness gate.
+*
+* `allowLaunch` is opt-in per script, and only tools whose whole purpose is to
+* make Notes do something set it. A read that silently launches Notes is a read
+* with a side effect.
+*/
+const script = (body, opts = {}) => `
+${PRELUDE}
+function run(argv) {
+  var p = JSON.parse(argv[0] || "{}");
+  if (!isNotesRunning() && !${opts.allowLaunch ? "true" : "false"}) {
+    return err("APP_NOT_RUNNING", "Notes is not running.");
+  }
+  try {
+    var N = Application("Notes");
+    ${body}
+  } catch (e) {
+    var msg = String(e && e.message ? e.message : e);
+    if (msg.indexOf("-1743") !== -1) return err("NOT_AUTHORIZED", msg);
+    return err("SCRIPT_ERROR", msg);
+  }
+}
+`;
+//#endregion
+//#region src/client/jxa/read.ts
+/** Accounts, with the folder count each one holds. */
+const LIST_ACCOUNTS = script(`
+  var accounts = N.accounts();
+  var out = [];
+  for (var i = 0; i < accounts.length; i++) {
+    var a = accounts[i];
+    out.push({
+      id: prop(function () { return String(a.id()); }, null),
+      name: prop(function () { return String(a.name()); }, null),
+      defaultFolder: prop(function () { return String(a.defaultFolder.name()); }, null),
+      folderCount: prop(function () { return a.folders().length; }, 0),
+      noteCount: prop(function () { return a.notes().length; }, 0)
+    });
+  }
+  return ok(out);
+`);
+/** The folder tree. Folders nest, so this is depth-first rather than a flat list. */
+const LIST_FOLDERS = script(`
+  var accounts = N.accounts();
+  var out = [];
+  for (var i = 0; i < accounts.length; i++) {
+    var a = accounts[i];
+    var accountId = prop(function () { return String(a.id()); }, null);
+    var accountName = prop(function () { return String(a.name()); }, null);
+    var folders = folderTree(a, accountId, 1, []);
+    for (var j = 0; j < folders.length; j++) {
+      folders[j].accountName = accountName;
+      out.push(folders[j]);
+    }
+  }
+  return ok(out);
+`);
+/**
+* Every note's metadata, as bulk arrays.
+*
+* One Apple Event per property for the whole library — ~0.1ms per note — versus
+* ~116ms per note for reading properties one note at a time. Folder membership
+* is resolved with one bulk call per *folder*, which is a handful of round trips
+* rather than one per note.
+*/
+const BULK_NOTES = script(`
+  var ids = N.notes.id();
+  var count = ids.length;
+  var rows = zip(
+    ["id", "name", "modified", "created", "locked", "shared"],
+    [
+      ids,
+      prop(function () { return N.notes.name(); }, []),
+      prop(function () { return N.notes.modificationDate(); }, []),
+      prop(function () { return N.notes.creationDate(); }, []),
+      prop(function () { return N.notes.passwordProtected(); }, []),
+      prop(function () { return N.notes.shared(); }, [])
+    ],
+    count
+  );
+
+  // Note -> folder, one bulk call per folder rather than one per note.
+  var folderOf = {};
+  var accounts = N.accounts();
+  for (var i = 0; i < accounts.length; i++) {
+    var a = accounts[i];
+    var accountId = prop(function () { return String(a.id()); }, null);
+    var accountName = prop(function () { return String(a.name()); }, null);
+    var folders = folderTree(a, accountId, 1, []);
+    for (var j = 0; j < folders.length; j++) {
+      var f = folders[j];
+      var noteIds = [];
+      try {
+        var handle = N.folders.byId(f.id);
+        noteIds = handle.notes.id();
+      } catch (e) { noteIds = []; }
+      for (var k = 0; k < noteIds.length; k++) {
+        folderOf[String(noteIds[k])] = { folderId: f.id, folder: f.name, accountId: accountId, account: accountName };
+      }
+    }
+  }
+
+  for (var r = 0; r < rows.length; r++) {
+    var row = rows[r];
+    row.id = String(row.id);
+    row.modified = iso(row.modified);
+    row.created = iso(row.created);
+    var where = folderOf[row.id];
+    row.folder = where ? where.folder : null;
+    row.folderId = where ? where.folderId : null;
+    row.account = where ? where.account : null;
+    row.accountId = where ? where.accountId : null;
+  }
+  return ok({ count: count, notes: rows });
+`);
+/**
+* Every note's id and plaintext, in one round trip.
+*
+* This is the search lane when the index is unavailable: pull everything, filter
+* in JS. Measured at 97ms over 921 notes and 250KB — against 671ms for the
+* equivalent `whose` specifier.
+*/
+const BULK_PLAINTEXT = script(`
+  return ok({ ids: N.notes.id(), texts: N.notes.plaintext() });
+`);
+/** Bodies for a specific set of notes, by id. Used after the index narrows things down. */
+const GET_NOTE_BODIES = script(`
+  var out = [];
+  for (var i = 0; i < p.ids.length; i++) {
+    var id = String(p.ids[i]);
+    var note = null;
+    try { note = N.notes.byId(id); } catch (e) { note = null; }
+    if (!note) { out.push({ id: id, found: false }); continue; }
+    var locked = prop(function () { return note.passwordProtected(); }, false);
+    out.push({
+      id: id,
+      found: true,
+      locked: locked,
+      name: prop(function () { return String(note.name()); }, null),
+      plaintext: locked ? null : prop(function () { return String(note.plaintext()); }, null),
+      body: locked ? null : prop(function () { return String(note.body()); }, null),
+      modified: iso(prop(function () { return note.modificationDate(); }, null)),
+      created: iso(prop(function () { return note.creationDate(); }, null))
+    });
+  }
+  return ok(out);
+`);
+/** Attachment metadata for one note. There is no filesystem path in the dictionary. */
+const LIST_ATTACHMENTS = script(`
+  var note = null;
+  try { note = N.notes.byId(String(p.id)); } catch (e) { note = null; }
+  if (!note) return err("NOTE_NOT_FOUND", "No note with id " + p.id);
+  var atts = prop(function () { return note.attachments(); }, []);
+  var out = [];
+  for (var i = 0; i < atts.length; i++) {
+    var a = atts[i];
+    out.push({
+      id: prop(function () { return String(a.id()); }, null),
+      name: prop(function () { return String(a.name()); }, null),
+      contentIdentifier: prop(function () { return String(a.contentIdentifier()); }, null),
+      url: prop(function () { return String(a.URL()); }, null),
+      created: iso(prop(function () { return a.creationDate(); }, null)),
+      modified: iso(prop(function () { return a.modificationDate(); }, null))
+    });
+  }
+  return ok(out);
+`);
+//#endregion
+//#region src/client/jxa/repair.ts
+/**
+* Repair for Notes' lossy `body` round trip.
+*
+* `UPDATE_NOTE`'s append mode reads `note.body()` and assigns the result back,
+* so whatever the getter mangles is written back mangled — onto content the
+* caller never touched. Two independent losses, both reproduced against Notes
+* on macOS 15:
+*
+* 1. **Entities come back unterminated.** The text `ps."projectId";` serialises
+*    to `ps.&quotprojectId&quot;` — `&quot` with no semicolon. Fed back to the
+*    setter, the trailing `&quot` fuses with the literal `;` that followed it
+*    into a single `"`, and the semicolon is gone. The getter never terminates
+*    an entity, so a `&quot;` in its output is always entity-plus-literal-`;`,
+*    never a well-formed `&quot;`. That is what makes the repair unconditional
+*    rather than a `(?!;)` lookahead — a lookahead would skip exactly the case
+*    that loses a character.
+* 2. **Space runs come back literal**, and HTML collapses them on re-parse, so
+*    every indented line loses its indentation and every aligned block loses
+*    its alignment.
+*
+* Order matters: entities first, then spaces. The space pass emits `&nbsp;`
+* with a terminating semicolon, and running the entity pass afterwards would
+* rewrite those into `&nbsp;;`.
+*
+* Exported as source rather than a function because it runs inside the JXA
+* script, in osascript's JavaScriptCore. `test/repair.test.ts` evaluates this
+* same string, so the tested code is the shipped code.
+*/
+const REPAIR_BODY_SRC = `
+var repairBody = function (html) {
+  var entities = html
+    .replace(/&(amp|quot|apos|lt|gt|nbsp)/g, "&$1;")
+    .replace(/&#(x?[0-9a-fA-F]+)/g, "&#$1;");
+  return entities.replace(/>([^<]*)</g, function (_m, text) {
+    return ">" + text
+      .replace(/ {2,}/g, function (run) { return new Array(run.length + 1).join("&nbsp;"); })
+      .replace(/^ /, "&nbsp;") + "<";
+  });
+};
+`;
+//#endregion
+//#region src/client/jxa/write.ts
+/**
+* Mutations may launch Notes.
+*
+* A read that silently launches an app is a read with a side effect, which is
+* why the read scripts refuse. A tool whose whole purpose is to create or change
+* a note has no such problem — the user asked for the change.
+*/
+const MUTATION = { allowLaunch: true };
+/**
+* Create a note.
+*
+* Notes derives a note's `name` from the first line of its body rather than from
+* a settable property, so the title is prepended as a heading instead of
+* assigned. Setting `name` directly is silently ignored.
+*/
+const CREATE_NOTE = script(`
+  var folder = null;
+  if (p.folderId) {
+    try { folder = N.folders.byId(String(p.folderId)); } catch (e) { folder = null; }
+    if (!folder) return err("FOLDER_NOT_FOUND", "No folder with id " + p.folderId);
+  } else {
+    var accounts = N.accounts();
+    if (!accounts.length) return err("NO_ACCOUNT", "Notes reports no accounts.");
+    folder = accounts[0].defaultFolder;
+  }
+
+  var html = "";
+  if (p.title) html += "<h1>" + p.title + "</h1>";
+  if (p.body) html += p.body;
+  if (!html) return err("EMPTY_NOTE", "A note needs a title or a body.");
+
+  var note = N.Note({ body: html });
+  folder.notes.push(note);
+  return ok({
+    id: prop(function () { return String(note.id()); }, null),
+    name: prop(function () { return String(note.name()); }, null),
+    folder: prop(function () { return String(folder.name()); }, null)
+  });
+`, MUTATION);
+/**
+* Replace a note's body. The title follows the first line, as it does on create.
+*
+* Append re-serialises the *existing* body through Notes' HTML parser, which is
+* lossy in both directions — see `repair.ts`. `repairBody` undoes the getter's
+* damage before the concatenation, so an append leaves untouched content byte
+* identical instead of silently flattening indentation and eating characters.
+*/
+const UPDATE_NOTE = script(REPAIR_BODY_SRC + `
+  var note = null;
+  try { note = N.notes.byId(String(p.id)); } catch (e) { note = null; }
+  if (!note) return err("NOTE_NOT_FOUND", "No note with id " + p.id);
+  if (prop(function () { return note.passwordProtected(); }, false)) {
+    return err("NOTE_LOCKED", "That note is password-protected; unlock it in Notes first.");
+  }
+
+  var current = prop(function () { return String(note.body()); }, "");
+  var next = p.mode === "append" ? repairBody(current) + (p.body || "") : (p.body || "");
+  note.body = next;
+  return ok({
+    id: String(p.id),
+    name: prop(function () { return String(note.name()); }, null),
+    bodyLength: next.length,
+    mode: p.mode || "replace"
+  });
+`, MUTATION);
+/** Move a note to another folder. */
+const MOVE_NOTE = script(`
+  var note = null;
+  try { note = N.notes.byId(String(p.id)); } catch (e) { note = null; }
+  if (!note) return err("NOTE_NOT_FOUND", "No note with id " + p.id);
+  var folder = null;
+  try { folder = N.folders.byId(String(p.folderId)); } catch (e) { folder = null; }
+  if (!folder) return err("FOLDER_NOT_FOUND", "No folder with id " + p.folderId);
+
+  N.move(note, { to: folder });
+  return ok({
+    id: String(p.id),
+    folder: prop(function () { return String(folder.name()); }, null)
+  });
+`, MUTATION);
+/**
+* Delete notes.
+*
+* Notes moves them to Recently Deleted rather than destroying them, which is
+* what makes this safe enough to expose at all — but it is still gated behind an
+* explicit confirm at the tool layer.
+*/
+const DELETE_NOTES = script(`
+  var deleted = [];
+  var missing = [];
+  for (var i = 0; i < p.ids.length; i++) {
+    var id = String(p.ids[i]);
+    var note = null;
+    try { note = N.notes.byId(id); } catch (e) { note = null; }
+    if (!note) { missing.push(id); continue; }
+    try { N.delete(note); deleted.push(id); } catch (e) { missing.push(id); }
+  }
+  return ok({ deleted: deleted, missing: missing, note: "Deleted notes go to Recently Deleted." });
+`, MUTATION);
+//#endregion
+//#region src/client/ref.ts
+/**
+* NoteRef — the one identifier any tool accepts or returns.
+*
+* Notes' own id is already globally unique and resolvable without a container,
+* unlike Mail's message ids: `x-coredata://<store>/ICNote/p<N>` addresses a note
+* outright, so this carries no folder and needs no lookup ladder.
+*
+* Wire format:  n1:<coredata-id>
+*
+* The `n1:` prefix is deliberate. If the id scheme ever changes, a versioned
+* prefix makes that an additive change instead of a silent reinterpretation of
+* every ref already in a conversation.
+*
+* Deliberately NOT shared with Mail's `ref.ts`: that codec's `#(\d+)$` and
+* `Number.isSafeInteger` both assume an integer id, which this is not.
+*/
+const REF_VERSION = "n1";
+/** `x-coredata://<uuid>/ICNote/p123` — the primary key is the trailing p-number. */
+const CORE_DATA_ID = /^x-coredata:\/\/[^/]+\/ICNote\/p(\d+)$/;
+const encodeRef = (id) => `n1:${id}`;
+const decodeRef = (raw) => {
+	const m = /^([a-z0-9]+):(.+)$/.exec(raw);
+	if (!m) throw new PreconditionError(`Malformed note ref "${raw}". Refs come from the search and list tools — construct them from those results rather than by hand.`, { expected: `n1:x-coredata://<store>/ICNote/p<N>` });
+	const [, version, id] = m;
+	if (version !== "n1") throw new PreconditionError(`Unknown note ref version "${version}". This server issues "n1:" refs.`);
+	const pk = CORE_DATA_ID.exec(id ?? "")?.[1];
+	if (!pk) throw new PreconditionError(`Note ref "${raw}" does not carry a Core Data note id.`);
+	return {
+		id,
+		primaryKey: Number(pk)
+	};
+};
+/** Build a ref from an index row, which only ever knows the primary key. */
+const refFromPrimaryKey = (storeUuid, primaryKey) => encodeRef(`x-coredata://${storeUuid}/ICNote/p${primaryKey}`);
+//#endregion
+//#region src/client/protobuf.ts
+/**
+* Minimal protobuf wire-format reader, enough to pull the body text out of a
+* `ZICNOTEDATA.ZDATA` blob.
+*
+* ## Why it does not hardcode Apple's schema
+*
+* The usual approach compiles Apple's unpublished `.proto` and reads
+* `document.note.note_text` by field number. That breaks the first time Apple
+* renumbers a field, and this project already budgets for the schema drifting
+* on every macOS release.
+*
+* So this walks the wire format structurally, and the path is *measured* rather
+* than assumed — see `NOTE_TEXT_PATH`.
+*
+* Wire format, for reference:
+*   tag = varint;  field = tag >> 3;  wire type = tag & 7
+*   0 varint · 1 fixed64 · 2 length-delimited · 5 fixed32 · 3/4 groups (legacy)
+*
+* Pure and I/O-free: callers gunzip, callers decide what to do with the result.
+*/
+/** Depth cap. Notes nests a handful deep; anything past this is a misparse. */
+const MAX_DEPTH = 8;
+/** Below this, a "string" is more likely coincidence than text. */
+const MIN_TEXT_LENGTH = 2;
+/** Above this share of control characters, the bytes are not text. */
+const MAX_CONTROL_RATIO = .05;
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+/** Tab, newline and carriage return are text; the rest of C0 and DEL are not. */
+const isControl = (code) => code < 32 && code !== 9 && code !== 10 && code !== 13 || code === 127;
+/** Read a base-128 varint. Returns null rather than throwing on a truncated one. */
+const readVarint = (buf, pos) => {
+	let value = 0;
+	let shift = 0;
+	let p = pos;
+	while (p < buf.length) {
+		const byte = buf[p];
+		p += 1;
+		if (shift > 45) return null;
+		value += (byte & 127) * 2 ** shift;
+		if ((byte & 128) === 0) return {
+			value,
+			next: p
+		};
+		shift += 7;
+	}
+	return null;
+};
+/**
+* Split a buffer into wire-format fields. Returns null if the bytes are not a
+* well-formed message ending exactly on the boundary — that "exactly" is what
+* makes this usable as a test for whether a blob is a nested message.
+*/
+const parseFields = (buf, start = 0, end = buf.length) => {
+	const fields = [];
+	let p = start;
+	while (p < end) {
+		const tag = readVarint(buf, p);
+		if (!tag) return null;
+		const field = Math.floor(tag.value / 8);
+		const wire = tag.value % 8;
+		if (field === 0) return null;
+		p = tag.next;
+		if (wire === 0) {
+			const v = readVarint(buf, p);
+			if (!v) return null;
+			fields.push({
+				field,
+				wire,
+				value: v.value
+			});
+			p = v.next;
+		} else if (wire === 2) {
+			const len = readVarint(buf, p);
+			if (!len) return null;
+			const from = len.next;
+			const to = from + len.value;
+			if (to > end) return null;
+			fields.push({
+				field,
+				wire,
+				from,
+				to
+			});
+			p = to;
+		} else if (wire === 1 || wire === 5) {
+			const width = wire === 1 ? 8 : 4;
+			if (p + width > end) return null;
+			fields.push({
+				field,
+				wire
+			});
+			p += width;
+		} else return null;
+	}
+	return p === end ? fields : null;
+};
+/** Valid UTF-8 that is mostly not control characters. */
+const asText = (bytes) => {
+	let text;
+	try {
+		text = utf8.decode(bytes);
+	} catch {
+		return null;
+	}
+	if (text.length < MIN_TEXT_LENGTH) return null;
+	let controls = 0;
+	for (let i = 0; i < text.length; i += 1) if (isControl(text.charCodeAt(i))) controls += 1;
+	return controls / text.length > MAX_CONTROL_RATIO ? null : text;
+};
+/**
+* Every string in the blob, with the field path that reached it.
+*
+* A length-delimited field can be both a valid message and valid text, so both
+* readings are followed. That ambiguity is the normal case, not an error.
+*/
+const collectStrings = (buf, maxDepth = MAX_DEPTH) => {
+	const out = [];
+	const walk = (start, end, path, depth) => {
+		if (depth > maxDepth) return;
+		const fields = parseFields(buf, start, end);
+		if (!fields) return;
+		for (const f of fields) {
+			if (f.wire !== 2 || f.from === void 0 || f.to === void 0) continue;
+			const here = [...path, f.field];
+			const text = asText(buf.subarray(f.from, f.to));
+			if (text) out.push({
+				path: here.join("."),
+				text,
+				length: text.length
+			});
+			walk(f.from, f.to, here, depth + 1);
+		}
+	};
+	walk(0, buf.length, [], 0);
+	return out;
+};
+/**
+* Where the body lives: `document(2) -> note(3) -> note_text(2)`.
+*
+* Measured, not assumed. Running the structural walk over 53 real notes and
+* checking each result against the same note's Apple Events plaintext, every
+* note read from this path matched exactly (53/53), and picking the longest
+* string instead matched only 27/53 — on the other 26 an attribute-run field
+* outran the body by ~60 characters. That failure is silent: it returns
+* plausible, wrong text rather than an error.
+*/
+const NOTE_TEXT_PATH = "2.3.2";
+/**
+* The note body.
+*
+* Reads the pinned path first and falls back to the longest string only if that
+* path is absent, reporting which route it took so drift is detectable rather
+* than silently wrong.
+*/
+const extractNoteText = (buf, preferPath = NOTE_TEXT_PATH) => {
+	const candidates = collectStrings(buf);
+	const pinned = preferPath ? candidates.find((c) => c.path === preferPath) ?? null : null;
+	const longest = candidates.toSorted((a, b) => b.length - a.length)[0] ?? null;
+	const best = pinned ?? longest;
+	return {
+		text: best?.text ?? null,
+		path: best?.path ?? null,
+		via: best === null ? null : pinned ? "pinned" : "longest",
+		candidateCount: candidates.length
+	};
+};
+//#endregion
+//#region src/client/store.ts
+/**
+* Read-only access to `NoteStore.sqlite`.
+*
+* Everything here is measured against a real store — see `docs/notes.md`. Three
+* facts do most of the work:
+*
+* 1. **`Z_ENT` alone is not "a note the user sees".** On the probed library it
+*    matched 1191 rows against 921 notes reported by Apple Events, and the two
+*    deletion columns explained none of the difference. `ZTITLE1 IS NOT NULL`
+*    reconciles them **exactly** — verified by comparing `Z_PK` sets, not counts.
+* 2. **No column holds the body.** `ZTITLE1` is the title (100% coverage) and
+*    `ZWIDGETSNIPPET` a ~86-character preview; the text lives in a gzipped
+*    protobuf in `ZICNOTEDATA.ZDATA`.
+* 3. **Dates are Core Data seconds**, offset 978307200.
+*/
+/** Every column this module reads, so a missing one is named rather than thrown at. */
+const REQUIRED_COLUMNS = [
+	"Z_PK",
+	"Z_ENT",
+	"ZTITLE1",
+	"ZMODIFICATIONDATE1",
+	"ZCREATIONDATE1"
+];
+const OPTIONAL = {
+	snippet: "ZSNIPPET",
+	widgetSnippet: "ZWIDGETSNIPPET",
+	folder: "ZFOLDER",
+	locked: "ZISPASSWORDPROTECTED"
+};
+const introspect = (db) => {
+	const cols = columnsOf(db, "ZICCLOUDSYNCINGOBJECT");
+	const missing = REQUIRED_COLUMNS.filter((c) => !cols.includes(c));
+	let noteEnt = null;
+	try {
+		noteEnt = db.prepare("SELECT Z_ENT FROM Z_PRIMARYKEY WHERE Z_NAME = 'ICNote'").get()?.Z_ENT ?? null;
+	} catch {
+		noteEnt = null;
+	}
+	if (noteEnt === null) missing.push("Z_PRIMARYKEY row for ICNote");
+	let storeUuid = null;
+	try {
+		storeUuid = db.prepare("SELECT Z_UUID FROM Z_METADATA LIMIT 1").get()?.Z_UUID ?? null;
+	} catch {
+		storeUuid = null;
+	}
+	return {
+		fingerprint: fingerprintSchema(db),
+		storeUuid,
+		noteEnt,
+		has: {
+			title: cols.includes("ZTITLE1"),
+			snippet: cols.includes(OPTIONAL.snippet),
+			widgetSnippet: cols.includes(OPTIONAL.widgetSnippet),
+			folder: cols.includes(OPTIONAL.folder),
+			locked: cols.includes(OPTIONAL.locked)
+		},
+		deletionColumns: cols.filter((c) => /^Z(ISRECOVERINGFROMTRASH|MARKEDFORDELETION)$/.test(c)),
+		missing
+	};
+};
+const assertUsable = (caps) => {
+	if (caps.missing.length) throw new SchemaDriftError(`NoteStore.sqlite is not the schema this server knows how to read (fingerprint ${caps.fingerprint}). Missing: ${caps.missing.join(", ")}. The index lane is unavailable; the Apple Events lane still works.`);
+};
+const toIso = (coreDataSeconds) => {
+	if (coreDataSeconds === null || !Number.isFinite(coreDataSeconds)) return null;
+	return (/* @__PURE__ */ new Date((coreDataSeconds + CORE_DATA_EPOCH_OFFSET) * 1e3)).toISOString();
+};
+var NoteStore = class {
+	#db;
+	caps;
+	mode;
+	constructor(db, caps, mode) {
+		this.#db = db;
+		this.caps = caps;
+		this.mode = mode;
+	}
+	/**
+	* The predicate for "a note the user sees".
+	*
+	* `Z_ENT` picks note rows; `ZTITLE1 IS NOT NULL` drops the title-less rows
+	* that Apple Events does not report. Verified by set equality against the
+	* 921 ids Apple Events returned — a matching count would not have been
+	* evidence, as the first ZDATA decoder demonstrated.
+	*/
+	#where() {
+		return `o.Z_ENT = ? AND o.ZTITLE1 IS NOT NULL${this.caps.deletionColumns.map((c) => ` AND (o."${c}" IS NULL OR o."${c}" = 0)`).join("")}`;
+	}
+	#select() {
+		return `SELECT o.Z_PK AS pk, o.ZTITLE1 AS title, ${this.caps.has.widgetSnippet ? "o.ZWIDGETSNIPPET" : this.caps.has.snippet ? "o.ZSNIPPET" : "NULL"} AS snippet,
+                   o.ZMODIFICATIONDATE1 AS modified, o.ZCREATIONDATE1 AS created,
+                   ${this.caps.has.folder ? "o.ZFOLDER" : "NULL"} AS folderPk, ${this.caps.has.locked ? "o.ZISPASSWORDPROTECTED" : "0"} AS locked
+            FROM ZICCLOUDSYNCINGOBJECT o`;
+	}
+	#toRow(r) {
+		return {
+			primaryKey: r.pk,
+			title: r.title ?? null,
+			snippet: r.snippet ?? null,
+			modified: toIso(r.modified ?? null),
+			created: toIso(r.created ?? null),
+			folderPk: r.folderPk ?? null,
+			locked: Boolean(r.locked)
+		};
+	}
+	count() {
+		return this.#db.prepare(`SELECT COUNT(*) AS c FROM ZICCLOUDSYNCINGOBJECT o WHERE ${this.#where()}`).get(this.caps.noteEnt).c;
+	}
+	/**
+	* Title and snippet search.
+	*
+	* Deliberately not full text: no indexed column carries the body. Callers that
+	* need body matching combine this with `bodyOf` or fall back to the Apple
+	* Events bulk scan.
+	*/
+	search(filters) {
+		const clauses = [this.#where()];
+		const params = [this.caps.noteEnt];
+		if (filters.query) {
+			const like = `%${escapeLike(filters.query)}%`;
+			const snippetCol = this.caps.has.widgetSnippet ? "o.ZWIDGETSNIPPET" : this.caps.has.snippet ? "o.ZSNIPPET" : null;
+			clauses.push(snippetCol ? `(o.ZTITLE1 LIKE ? ESCAPE '\\' OR ${snippetCol} LIKE ? ESCAPE '\\')` : `o.ZTITLE1 LIKE ? ESCAPE '\\'`);
+			params.push(like);
+			if (snippetCol) params.push(like);
+		}
+		if (filters.folderPk !== void 0 && this.caps.has.folder) {
+			clauses.push("o.ZFOLDER = ?");
+			params.push(filters.folderPk);
+		}
+		if (filters.modifiedAfter) {
+			clauses.push("o.ZMODIFICATIONDATE1 >= ?");
+			params.push(Date.parse(filters.modifiedAfter) / 1e3 - CORE_DATA_EPOCH_OFFSET);
+		}
+		if (filters.modifiedBefore) {
+			clauses.push("o.ZMODIFICATIONDATE1 <= ?");
+			params.push(Date.parse(filters.modifiedBefore) / 1e3 - CORE_DATA_EPOCH_OFFSET);
+		}
+		const sql = `${this.#select()} WHERE ${clauses.join(" AND ")}
+                 ORDER BY o.ZMODIFICATIONDATE1 DESC LIMIT ? OFFSET ?`;
+		params.push(filters.limit, filters.offset);
+		return this.#db.prepare(sql).all(...params).map((r) => this.#toRow(r));
+	}
+	byPrimaryKey(pk) {
+		const row = this.#db.prepare(`${this.#select()} WHERE ${this.#where()} AND o.Z_PK = ?`).get(this.caps.noteEnt, pk);
+		return row ? this.#toRow(row) : null;
+	}
+	/**
+	* The note body, decoded from the gzipped protobuf.
+	*
+	* Returns null for password-protected notes: their `ZDATA` is AES ciphertext,
+	* flagged by a non-null `ZCRYPTOTAG`. No permission makes that readable.
+	*/
+	bodyOf(pk) {
+		const row = this.#db.prepare("SELECT ZDATA AS data, ZCRYPTOTAG AS tag FROM ZICNOTEDATA WHERE ZNOTE = ?").get(pk);
+		if (!row?.data) return {
+			text: null,
+			via: null,
+			encrypted: false
+		};
+		if (row.tag) return {
+			text: null,
+			via: null,
+			encrypted: true
+		};
+		const blob = Buffer.from(row.data);
+		if (blob[0] !== 31 || blob[1] !== 139) return {
+			text: null,
+			via: null,
+			encrypted: false
+		};
+		let inflated;
+		try {
+			inflated = gunzipSync(blob);
+		} catch {
+			return {
+				text: null,
+				via: null,
+				encrypted: false
+			};
+		}
+		const decoded = extractNoteText(inflated);
+		return {
+			text: decoded.text,
+			via: decoded.via,
+			encrypted: false
+		};
+	}
+	close() {
+		this.#db.close();
+	}
+};
+const openStore = (path, mode, logger) => {
+	const { db, mode: opened, validated: caps } = openReadOnly(path, mode, {
+		envVar: "APPLE_NOTES_INDEX_MODE",
+		label: "Notes' store",
+		hint: "If this is a permission error, grant Full Disk Access to the app running this server.",
+		validate: (conn) => {
+			const found = introspect(conn);
+			assertUsable(found);
+			return found;
+		},
+		fatal: (err) => err instanceof SchemaDriftError,
+		onFallback: () => logger?.warn?.("opened the store with immutable=1; results may omit notes still in the -wal")
+	});
+	return new NoteStore(db, caps, opened);
+};
+//#endregion
+//#region src/client/notes.ts
+/**
+* The Notes client.
+*
+* Two lanes, and which one answers depends on what was granted:
+*
+* - **Apple Events** — accounts, folders, every mutation, and bodies. Always the
+*   authority: after a write, the result is what Notes re-read.
+* - **Index** — `NoteStore.sqlite`, for search and metadata at a scale Apple
+*   Events cannot reach.
+*
+* The discipline the measurements impose is in `jxa/core.ts`: bulk array fetches
+* only, never `whose`, never a property read per note.
+*/
+var AppleNotesClient = class {
+	config;
+	runner;
+	#logger;
+	#store = null;
+	#storeTried = false;
+	#bodies = null;
+	constructor(opts) {
+		this.config = opts.config;
+		this.#logger = opts.logger;
+		this.runner = opts.osascript ?? createOsascriptRunner({
+			osascriptPath: opts.config.osascriptPath,
+			timeoutMs: opts.config.osascriptTimeoutMs,
+			surface: NOTES_SURFACE,
+			logger: opts.logger
+		});
+	}
+	locate() {
+		return locateStore({ storePath: this.config.storePath });
+	}
+	/** Open the index once and remember the outcome, including the failure. */
+	index() {
+		if (this.#storeTried) return this.#store;
+		this.#storeTried = true;
+		if (this.config.indexMode === "off") return null;
+		try {
+			this.#store = openStore(this.locate().storePath, this.config.indexMode, this.#logger);
+		} catch (err) {
+			this.#logger?.debug?.("index lane unavailable", err);
+			this.#store = null;
+		}
+		return this.#store;
+	}
+	/**
+	* Probe both lanes.
+	*
+	* Apple Events is probed twice with a gap: the first event is what triggers
+	* the Automation prompt, and it can return failure while the user is still
+	* deciding — reporting "denied" then would be wrong.
+	*/
+	async lanes() {
+		let applescript = "unavailable";
+		for (let attempt = 0; attempt < 2; attempt += 1) try {
+			await this.runner.run(LIST_ACCOUNTS);
+			applescript = "live";
+			break;
+		} catch (err) {
+			this.#logger?.debug?.("applescript probe failed", err);
+			if (attempt === 0) await new Promise((r) => setTimeout(r, 400));
+		}
+		const located = this.locate();
+		const store = this.index();
+		return {
+			applescript,
+			index: this.config.indexMode === "off" ? "disabled" : store ? "live" : "unavailable",
+			indexMode: store?.mode ?? null,
+			storeFingerprint: store?.caps.fingerprint ?? null,
+			reason: store ? null : located.reason
+		};
+	}
+	#allowed(accountName) {
+		const list = this.config.accounts;
+		if (!list.length) return true;
+		return Boolean(accountName && list.some((a) => a.toLowerCase() === accountName.toLowerCase()));
+	}
+	async accounts() {
+		return (await withBusyRetry(() => this.runner.run(LIST_ACCOUNTS))).filter((a) => this.#allowed(a.name));
+	}
+	async folders() {
+		return (await withBusyRetry(() => this.runner.run(LIST_FOLDERS))).filter((f) => this.#allowed(f.accountName));
+	}
+	/**
+	* Note metadata.
+	*
+	* Prefers the index — it holds the same fields, costs no Apple Event, and
+	* keeps working as a library grows past the point where a bulk fetch stops
+	* being instant.
+	*/
+	async listNotes(opts) {
+		const store = this.index();
+		if (store?.caps.storeUuid) {
+			const folderPk = opts.folder ? await this.#folderPk(opts.folder) : void 0;
+			return store.search({
+				...folderPk === void 0 ? {} : { folderPk },
+				limit: opts.limit,
+				offset: 0
+			}).map((r) => this.#fromIndex(r, store.caps.storeUuid));
+		}
+		return this.#bulkNotes(opts);
+	}
+	async #folderPk(_name) {}
+	#fromIndex(row, storeUuid) {
+		return {
+			ref: refFromPrimaryKey(storeUuid, row.primaryKey),
+			title: row.title,
+			snippet: row.snippet,
+			folder: null,
+			account: null,
+			modified: row.modified,
+			created: row.created,
+			locked: row.locked,
+			source: "index"
+		};
+	}
+	async #bulkNotes(opts) {
+		return (await withBusyRetry(() => this.runner.run(BULK_NOTES))).notes.filter((n) => this.#allowed(n.account)).filter((n) => !opts.folder || n.folder === opts.folder).slice(0, Math.min(opts.limit, this.config.degradedMaxNotes)).map((n) => ({
+			ref: encodeRef(n.id),
+			title: n.name,
+			snippet: null,
+			folder: n.folder,
+			account: n.account,
+			modified: n.modified,
+			created: n.created,
+			locked: n.locked,
+			source: "apple-events"
+		}));
+	}
+	/**
+	* Body text for every note, cached.
+	*
+	* A TTL rather than invalidation, deliberately: checking whether the cache is
+	* stale costs *more* over Apple Events (fetching ids and modification dates,
+	* 128ms) than simply redoing the scan (97ms). There is no cheap freshness
+	* check to be had, so bounded staleness is the honest trade.
+	*/
+	async #allBodies() {
+		const now = Date.now();
+		if (this.#bodies && now - this.#bodies.at < this.config.searchCacheTtlMs) return this.#bodies;
+		const store = this.index();
+		const texts = /* @__PURE__ */ new Map();
+		if (store?.caps.storeUuid) {
+			const uuid = store.caps.storeUuid;
+			for (const row of store.search({
+				limit: 1e5,
+				offset: 0
+			})) {
+				const body = store.bodyOf(row.primaryKey);
+				if (body.text) texts.set(refFromPrimaryKey(uuid, row.primaryKey), body.text);
+			}
+			this.#bodies = {
+				at: now,
+				source: "index",
+				texts
+			};
+			return this.#bodies;
+		}
+		const bulk = await withBusyRetry(() => this.runner.run(BULK_PLAINTEXT));
+		bulk.ids.forEach((id, i) => {
+			const text = bulk.texts[i];
+			if (text) texts.set(encodeRef(String(id)), String(text));
+		});
+		this.#bodies = {
+			at: now,
+			source: "apple-events",
+			texts
+		};
+		return this.#bodies;
+	}
+	/**
+	* Search.
+	*
+	* `title` uses the index's title and snippet columns, which is a SQL query.
+	* `full` needs the body, which no indexed column carries — so it decodes the
+	* gzipped protobuf when the index is available and falls back to the Apple
+	* Events bulk scan when it is not. Either way the match happens in JS over a
+	* cached corpus, because `whose` is 6.9x slower than fetching and filtering.
+	*/
+	async searchNotes(opts) {
+		const store = this.index();
+		if (opts.scope === "title" && store?.caps.storeUuid) return {
+			notes: store.search({
+				query: opts.query,
+				limit: opts.limit,
+				offset: opts.offset
+			}).map((r) => this.#fromIndex(r, store.caps.storeUuid)),
+			source: "index",
+			scope: "title+snippet"
+		};
+		const corpus = await this.#allBodies();
+		const needle = opts.query.toLowerCase();
+		const hits = [];
+		for (const [ref, text] of corpus.texts) if (text.toLowerCase().includes(needle)) hits.push(ref);
+		const page = hits.slice(opts.offset, opts.offset + opts.limit);
+		return {
+			notes: (await Promise.all(page.map((ref) => this.getNote(ref, { body: false })))).map((s) => s.summary),
+			source: corpus.source,
+			scope: "full-text"
+		};
+	}
+	async getNote(ref, opts = {}) {
+		const decoded = decodeRef(ref);
+		const store = this.index();
+		if (store?.caps.storeUuid) {
+			const row = store.byPrimaryKey(decoded.primaryKey);
+			if (row) {
+				const summary = this.#fromIndex(row, store.caps.storeUuid);
+				if (opts.body === false) return {
+					summary,
+					body: null,
+					bodySource: null
+				};
+				if (row.locked) throw new NoteLockedError(ref);
+				const body = store.bodyOf(decoded.primaryKey);
+				if (body.encrypted) throw new NoteLockedError(ref);
+				if (body.text !== null) return {
+					summary,
+					body: this.#truncate(body.text),
+					bodySource: `index:${body.via}`
+				};
+			}
+		}
+		const [found] = await withBusyRetry(() => this.runner.run(GET_NOTE_BODIES, { ids: [decoded.id] }));
+		if (!found?.found) throw new NoteNotFoundError(ref);
+		if (found.locked) throw new NoteLockedError(ref);
+		return {
+			summary: {
+				ref,
+				title: found.name,
+				snippet: null,
+				folder: null,
+				account: null,
+				modified: found.modified,
+				created: found.created,
+				locked: false,
+				source: "apple-events"
+			},
+			body: found.plaintext === null ? null : this.#truncate(found.plaintext),
+			bodySource: "apple-events"
+		};
+	}
+	#truncate(text) {
+		const max = this.config.bodyMaxBytes;
+		if (Buffer.byteLength(text, "utf8") <= max) return text;
+		return `${text.slice(0, max)}\n\n[truncated at ${max} bytes; raise APPLE_NOTES_BODY_MAX_BYTES]`;
+	}
+	async attachments(ref) {
+		const decoded = decodeRef(ref);
+		return withBusyRetry(() => this.runner.run(LIST_ATTACHMENTS, { id: decoded.id }));
+	}
+	/**
+	* Save an attachment's bytes.
+	*
+	* The scripting dictionary exposes `name`, `id`, `URL` and `content
+	* identifier` but **no filesystem path**, so the bytes can only come from the
+	* media directory — which is Full Disk Access territory. Without it this
+	* reports what is missing rather than failing obscurely.
+	*/
+	async saveAttachment(ref, attachmentId, targetDir, opts = {}) {
+		const located = this.locate();
+		if (!located.readable) throw new PreconditionError("Attachment bytes need Full Disk Access: the scripting dictionary carries no file path for attachments, so they can only be read from the Notes media directory. Call apple_notes_diagnostics for the exact pane to open.");
+		const meta = (await this.attachments(ref)).find((a) => a.id === attachmentId);
+		if (!meta) throw new PreconditionError(`No attachment ${attachmentId} on note ${ref}.`);
+		const source = this.#findMedia(located.mediaRoot, attachmentId, meta.name);
+		if (!source) throw new PreconditionError(`Found the attachment's metadata but no file for it under ${located.mediaRoot}.`);
+		const root = resolve(this.config.attachmentDir);
+		const dir = targetDir ? resolve(root, targetDir) : root;
+		if (dir !== root && !dir.startsWith(root + sep)) throw new PreconditionError(`Refusing to write outside ${root}. Set APPLE_NOTES_ATTACHMENT_DIR to change the destination.`);
+		const name = basename(meta.name ?? basename(source));
+		const target = resolve(join(dir, name));
+		if (target !== join(dir, name) || !target.startsWith(dir + sep)) throw new PreconditionError(`Refusing to write outside ${dir}.`);
+		if (existsSync(target) && !opts.overwrite) throw new PreconditionError(`${target} already exists; refusing to overwrite it.`);
+		const bytes = readFileSync(source);
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(target, bytes, { mode: 384 });
+		return {
+			path: target,
+			bytes: bytes.length
+		};
+	}
+	/** Bounded walk for a file whose directory is named after the attachment id. */
+	#findMedia(root, attachmentId, name, depth = 0) {
+		if (depth > 5) return null;
+		let entries;
+		try {
+			entries = readdirSync(root);
+		} catch {
+			return null;
+		}
+		for (const entry of entries) {
+			const full = join(root, entry);
+			let isDir = false;
+			try {
+				isDir = statSync(full).isDirectory();
+			} catch {
+				continue;
+			}
+			if (isDir) {
+				if (entry === attachmentId) {
+					const inner = (() => {
+						try {
+							return readdirSync(full);
+						} catch {
+							return [];
+						}
+					})();
+					const pick = name ? inner.find((f) => f === name) ?? inner[0] : inner[0];
+					if (pick) return join(full, pick);
+				}
+				const found = this.#findMedia(full, attachmentId, name, depth + 1);
+				if (found) return found;
+			}
+		}
+		return null;
+	}
+	async createNote(opts) {
+		this.#bodies = null;
+		return withBusyRetry(() => this.runner.run(CREATE_NOTE, opts));
+	}
+	async updateNote(ref, body, mode) {
+		this.#bodies = null;
+		const decoded = decodeRef(ref);
+		return withBusyRetry(() => this.runner.run(UPDATE_NOTE, {
+			id: decoded.id,
+			body,
+			mode
+		}));
+	}
+	async moveNote(ref, folderId) {
+		this.#bodies = null;
+		const decoded = decodeRef(ref);
+		return withBusyRetry(() => this.runner.run(MOVE_NOTE, {
+			id: decoded.id,
+			folderId
+		}));
+	}
+	async deleteNotes(refs) {
+		this.#bodies = null;
+		const ids = refs.map((r) => decodeRef(r).id);
+		return withBusyRetry(() => this.runner.run(DELETE_NOTES, { ids }));
+	}
+};
+//#endregion
+//#region src/config.ts
+/**
+* Configuration is environment-only — this server holds no secret at all, its
+* access is the macOS permission the user granted.
+*
+* `allowWrites`, `debug`, `osascriptPath`, `osascriptTimeoutMs` and `maxResults`
+* come from `BaseConfigSchema`.
+*/
+const ConfigSchema = BaseConfigSchema.extend({
+	/**
+	* Account allowlist (names or ids). Empty means every account.
+	*
+	* `allowWrites` gates mutation, but the larger blast radius is *reading* a
+	* person's whole notebook, so this is the read-side control.
+	*/
+	accounts: z.array(z.string().min(1)).default([]),
+	/** Explicit NoteStore.sqlite path. Bypasses discovery — for tests and forensic copies. */
+	storePath: z.string().optional(),
+	indexMode: z.enum([
+		"auto",
+		"ro",
+		"immutable",
+		"off"
+	]).default("auto"),
+	/**
+	* Cap for the Apple Events listing lane. Generous compared to Mail's because
+	* a bulk property fetch here is one round trip at ~0.1ms per note, not 42ms.
+	*/
+	degradedMaxNotes: z.number().int().min(1).max(1e3).default(200),
+	bodyMaxBytes: z.number().int().min(1024).max(1e7).default(262144),
+	/**
+	* The confinement boundary for save_attachment, not merely its default: the
+	* tool's `directory` argument may select a subdirectory of this, never escape
+	* it. Enforced lexically with `resolve()` + `basename()`, not `realpath()` —
+	* the destination may not exist yet.
+	*/
+	attachmentDir: z.string().default(join(homedir(), "Downloads")),
+	/**
+	* How long the Apple Events plaintext cache stays warm.
+	*
+	* Measured: fetching ids + modification dates to check freshness costs *more*
+	* (128ms) than simply re-scanning every body (97ms), so there is no cheap
+	* invalidation to be had. A TTL with bounded staleness is the only sensible
+	* trade when the index lane is unavailable.
+	*/
+	searchCacheTtlMs: z.number().int().min(0).max(36e5).default(6e4)
+}).strict();
+/**
+* `env` is a parameter with a default so tests are hermetic — they pass their
+* own object rather than mutating (and having to restore) process.env.
+*/
+const loadConfig = (env = process.env) => parseConfig(ConfigSchema, {
+	allowWrites: parseBool(env.APPLE_NOTES_ALLOW_WRITES),
+	debug: parseBool(env.APPLE_NOTES_DEBUG),
+	accounts: parseList(env.APPLE_NOTES_ACCOUNTS),
+	storePath: trimmed(env.APPLE_NOTES_STORE),
+	indexMode: trimmed(env.APPLE_NOTES_INDEX_MODE),
+	osascriptPath: trimmed(env.APPLE_NOTES_OSASCRIPT_PATH),
+	osascriptTimeoutMs: parseIntOpt(env.APPLE_NOTES_OSASCRIPT_TIMEOUT_MS),
+	maxResults: parseIntOpt(env.APPLE_NOTES_MAX_RESULTS),
+	degradedMaxNotes: parseIntOpt(env.APPLE_NOTES_DEGRADED_MAX_NOTES),
+	bodyMaxBytes: parseIntOpt(env.APPLE_NOTES_BODY_MAX_BYTES),
+	attachmentDir: trimmed(env.APPLE_NOTES_ATTACHMENT_DIR),
+	searchCacheTtlMs: parseIntOpt(env.APPLE_NOTES_SEARCH_CACHE_TTL_MS)
+});
+//#endregion
+//#region src/tools/util.ts
+const noteRefArg = z.string().min(1).describe("An opaque note ref from a search or list result (looks like \"n1:x-coredata://…/ICNote/p123\"). Do not construct one by hand.");
+const noteRefsArg = z.array(z.string().min(1)).min(1).max(200).describe("Note refs from a search or list result.");
+const folderArg = z.string().optional().describe("Folder name, e.g. \"Notes\" or \"Projects\". Folders nest; give the leaf name.");
+const folderIdArg = z.string().min(1).describe("A folder id from apple_notes_list_folders.");
+//#endregion
+//#region src/tools/accounts.ts
+const registerAccountTools = (server, client) => {
+	server.registerTool("apple_notes_list_accounts", {
+		description: "List the Notes accounts, with how many folders and notes each holds. Start here to discover account names for the other tools.",
+		inputSchema: {},
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(() => client.accounts()));
+	server.registerTool("apple_notes_list_folders", {
+		description: "List folders across every account. Folders nest, so each entry carries its depth and the account it belongs to. Use the returned id with the move and create tools.",
+		inputSchema: {},
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(() => client.folders()));
+};
+//#endregion
+//#region src/tools/actions.ts
+/**
+* The mutating tools.
+*
+* Registered only when writes are enabled, so with the flag off they are
+* invisible to the model rather than merely refused.
+*/
+const registerActionTools = (server, client) => {
+	server.registerTool("apple_notes_create_note", {
+		description: "Create a note. Notes takes its title from the first line of the body, so `title` is prepended as a heading rather than set as a property.",
+		inputSchema: {
+			title: z.string().optional().describe("Becomes the first line, and therefore the title."),
+			body: z.string().optional().describe("Body content. Simple HTML is accepted."),
+			folderId: z.string().optional().describe("Target folder id. Defaults to the first account's default folder.")
+		}
+	}, async ({ title, body, folderId }) => wrap(() => client.createNote({
+		title,
+		body,
+		folderId
+	})));
+	server.registerTool("apple_notes_update_note", {
+		description: "Replace or append to a note's body. Editing the first line changes the title, because that is where Notes takes it from.",
+		inputSchema: {
+			ref: noteRefArg,
+			body: z.string().min(1).describe("The new content. Simple HTML is accepted."),
+			mode: z.enum(["replace", "append"]).optional().describe("replace overwrites the body (default). append adds to the end.")
+		}
+	}, async ({ ref, body, mode }) => wrap(() => client.updateNote(ref, body, mode ?? "replace")));
+	server.registerTool("apple_notes_move_note", {
+		description: "Move a note to another folder.",
+		inputSchema: {
+			ref: noteRefArg,
+			folderId: folderIdArg
+		}
+	}, async ({ ref, folderId }) => wrap(() => client.moveNote(ref, folderId)));
+	server.registerTool("apple_notes_delete_notes", {
+		description: "Delete notes. They go to Recently Deleted rather than being destroyed, but this still requires an explicit confirm.",
+		inputSchema: {
+			refs: noteRefsArg,
+			confirm: confirmArg
+		}
+	}, async ({ refs }) => wrap(() => client.deleteNotes(refs)));
+};
+//#endregion
+//#region src/tools/diagnostics.ts
+/**
+* One tool that answers "why is this not working".
+*
+* Lanes are probed before anything else is read, because the first Apple Event
+* is what triggers the Automation prompt: reading accounts first and probing
+* afterwards makes the two disagree whenever that first event loses the race.
+*/
+const registerDiagnosticsTools = (server, client, ctx) => {
+	server.registerTool("apple_notes_diagnostics", {
+		description: "Report which lanes are live, which macOS permissions are granted, and what each missing one is blocking. Start here when a tool returns degraded or fails — it names the exact System Settings pane to open.",
+		inputSchema: {},
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(async () => {
+		const lanes = await client.lanes();
+		const located = client.locate();
+		const accounts = lanes.applescript === "live" ? await client.accounts() : [];
+		const fullDiskAccess = located.readable ? "granted" : located.exists ? "denied" : "unknown (no store found)";
+		return {
+			server: { lanes },
+			permissions: {
+				automation: lanes.applescript === "live" ? "granted" : "denied-or-notes-not-running",
+				fullDiskAccess,
+				...located.readable ? {} : { howToGrant: [
+					"System Settings > Privacy & Security > Full Disk Access",
+					"Add the app that launches this server (Terminal, iTerm, VS Code, Claude...), then restart it.",
+					"Granting it to Notes.app does nothing — the reader needs the permission, not Notes."
+				] }
+			},
+			store: {
+				path: located.storePath,
+				exists: located.exists,
+				readable: located.readable,
+				sizeBytes: located.size,
+				walPresent: located.walPresent,
+				walSizeBytes: located.walSizeBytes,
+				fingerprint: lanes.storeFingerprint,
+				reason: located.reason
+			},
+			accounts,
+			settings: {
+				allowWrites: ctx.allowWrites,
+				accountAllowlist: client.config.accounts,
+				indexMode: client.config.indexMode,
+				maxResults: client.config.maxResults,
+				searchCacheTtlMs: client.config.searchCacheTtlMs,
+				attachmentDir: client.config.attachmentDir
+			},
+			caveats: [
+				"Without Full Disk Access the index lane is unavailable: search falls back to an Apple Events bulk scan, which is fine on a small library and degrades linearly.",
+				"Password-protected notes are encrypted at rest; no permission makes them readable.",
+				"Attachment bytes need Full Disk Access — the scripting dictionary carries no file path."
+			]
+		};
+	}).then((r) => r ?? ok({})));
+};
+//#endregion
+//#region src/tools/notes.ts
+const registerNoteTools = (server, client, allowWrites) => {
+	server.registerTool("apple_notes_list_notes", {
+		description: "List notes, newest first. Returns a `ref` per note for the read and action tools. Prefers Notes' own index, which stays fast as a library grows.",
+		inputSchema: {
+			folder: folderArg,
+			limit: limitArg
+		},
+		annotations: { readOnlyHint: true }
+	}, async ({ folder, limit }) => wrap(() => client.listNotes({
+		folder,
+		limit: limit ?? Math.min(25, client.config.maxResults)
+	})));
+	server.registerTool("apple_notes_search_notes", {
+		description: "Search notes. `scope: \"full\"` (the default) matches the body text; `scope: \"title\"` matches only titles and previews and is the cheaper query. Returns a `ref` per hit.",
+		inputSchema: {
+			query: z.string().min(1).describe("Text to look for. Case-insensitive substring match."),
+			scope: z.enum(["full", "title"]).optional().describe("full = search body text (default). title = titles and previews only, which is a single indexed query and cheaper on a large library."),
+			limit: limitArg,
+			offset: z.number().int().min(0).optional().describe("Skip this many results, for paging.")
+		},
+		annotations: { readOnlyHint: true }
+	}, async ({ query, scope, limit, offset }) => wrap(() => client.searchNotes({
+		query,
+		scope: scope ?? "full",
+		limit: limit ?? Math.min(25, client.config.maxResults),
+		offset: offset ?? 0
+	})));
+	server.registerTool("apple_notes_get_note", {
+		description: "Read one note's full text by ref. Password-protected notes report as locked rather than returning an empty body — their text is encrypted at rest.",
+		inputSchema: {
+			ref: noteRefArg,
+			format: z.enum(["text", "json"]).optional().describe("text returns the body as-is (default). json wraps it with the metadata.")
+		},
+		annotations: { readOnlyHint: true }
+	}, async ({ ref, format }) => wrapResult(async () => {
+		const result = await client.getNote(ref);
+		if ((format ?? "text") === "text" && result.body !== null) return okText(result.body);
+		return ok(result);
+	}));
+	server.registerTool("apple_notes_list_attachments", {
+		description: "List a note's attachments. Metadata only — retrieving the bytes needs Full Disk Access, because the scripting dictionary carries no file path.",
+		inputSchema: { ref: noteRefArg },
+		annotations: { readOnlyHint: true }
+	}, async ({ ref }) => wrap(() => client.attachments(ref)));
+	if (!allowWrites) return;
+	server.registerTool("apple_notes_save_attachment", {
+		description: "Save one attachment to disk. Needs Full Disk Access. It can only write into APPLE_NOTES_ATTACHMENT_DIR (default ~/Downloads) and will not overwrite an existing file unless you ask it to. Write-gated because it puts a file on the user's disk, even though it changes nothing in Notes.",
+		inputSchema: {
+			ref: noteRefArg,
+			attachmentId: z.string().min(1).describe("An id from apple_notes_list_attachments."),
+			directory: z.string().optional().describe("Override the target directory. Must still resolve inside the configured one."),
+			overwrite: z.boolean().optional().describe("Replace an existing file. Default false.")
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ ref, attachmentId, directory, overwrite }) => wrap(() => client.saveAttachment(ref, attachmentId, directory, overwrite ? { overwrite } : {})));
+};
+//#endregion
+//#region src/tools/index.ts
+/**
+* Register the Apple Notes tools.
+*
+* The registered set is a pure function of `allowWrites` and nothing else. In
+* particular it does NOT vary with whether Full Disk Access is granted: that is
+* a runtime condition which can change while the process lives, and MCP clients
+* cache the tool list, so a tool that appears and disappears would leave clients
+* calling names the server no longer has. Tools that need the index instead
+* report their source, or explain what is missing.
+*/
+const registerTools = (server, client, ctx) => {
+	registerDiagnosticsTools(server, client, ctx);
+	registerAccountTools(server, client);
+	registerNoteTools(server, client, ctx.allowWrites);
+	if (!ctx.allowWrites) return;
+	registerActionTools(server, client);
+};
+//#endregion
+//#region src/server.ts
+const SERVER_NAME = BUILD_INFO.name;
+const SERVER_VERSION = BUILD_INFO.version;
+/**
+* Build the server. Side-effect free: it opens no connection, spawns no
+* process and reads no file, so a test can construct it freely and every
+* external dependency arrives through an option.
+*/
+const createServer = (opts) => {
+	const { config } = opts;
+	const server = new McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	});
+	const client = new AppleNotesClient({
+		config,
+		...opts.logger ? { logger: opts.logger } : {},
+		...opts.osascript ? { osascript: opts.osascript } : {}
+	});
+	registerTools(server, client, { allowWrites: config.allowWrites });
+	return {
+		server,
+		client
+	};
+};
+//#endregion
+export { NoteLockedError as C, BUILD_INFO as D, NotesNotRunningError as E, NOTES_SURFACE as S, NotesBusyError as T, encodeRef as _, loadConfig as a, locateStore as b, introspect as c, collectStrings as d, extractNoteText as f, decodeRef as g, REF_VERSION as h, registerTools as i, openStore as l, readVarint as m, SERVER_VERSION as n, AppleNotesClient as o, parseFields as p, createServer as r, NoteStore as s, SERVER_NAME as t, NOTE_TEXT_PATH as u, refFromPrimaryKey as v, NoteNotFoundError as w, AppleNotesError as x, defaultStorePath as y };
+
+//# sourceMappingURL=server-HLS_dM7r.js.map