@mgcrea/mcp-apple-core 1.15.0 → 1.17.0

package/dist/index.js

@@ -1,9 +1,327 @@
+import { connect } from "node:net";
 import { accessSync, constants, readFileSync, statSync } from "node:fs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { DatabaseSync } from "node:sqlite";
+//#region src/errors.ts
+/** Base class so `toFailure` can carry structured detail through in one branch. */
+var AppleAutomationError = class extends Error {
+	name = "AppleAutomationError";
+	details;
+	constructor(message, details) {
+		super(message);
+		this.details = details;
+	}
+};
+/** The host process may not send Apple Events to the app (osascript -1743). */
+var TccDeniedError = class extends AppleAutomationError {
+	name = "TccDeniedError";
+	constructor(surface) {
+		super(`Not authorized to control ${surface.appName}. Grant it in System Settings > Privacy & Security > Automation > (the app running this server) > ${surface.appName}, then restart the server. If no entry appears, the first attempt was denied before the prompt could be answered — run \`tccutil reset AppleEvents\` and try again.`);
+	}
+};
+/** The app is not running and the operation refuses to launch it. */
+var AppNotRunningError = class extends AppleAutomationError {
+	name = "AppNotRunningError";
+	constructor(surface) {
+		super(`${surface.appName} is not running. Read tools do not launch it, because launching it steals focus and can start a sync. Open ${surface.appName} and retry.`);
+	}
+};
+/** The app was busy and refused the Apple Event (-1712). Retried once before surfacing. */
+var AppBusyError = class extends AppleAutomationError {
+	name = "AppBusyError";
+	constructor(surface) {
+		super(`${surface.appName} is busy (probably syncing) and did not answer in time. Retry in a few seconds.`);
+	}
+};
+/** osascript exceeded its budget and was killed. */
+var OsascriptTimeoutError = class extends AppleAutomationError {
+	name = "OsascriptTimeoutError";
+	constructor(timeoutMs, surface) {
+		super(`${surface.appName} did not answer within ${timeoutMs}ms. It may be mid-sync, or a permission prompt may be waiting on screen. Raise ${surface.envPrefix}_OSASCRIPT_TIMEOUT_MS if this is routine at your data size.`);
+	}
+};
+/**
+* A write was attempted while writes are disabled. Under the house pattern write
+* tools are not registered at all when `allowWrites` is off, so this is a
+* belt-and-braces guard for the library surface, not a path tools can reach.
+*/
+var WritesDisabledError = class extends AppleAutomationError {
+	name = "WritesDisabledError";
+	constructor(surface) {
+		super(`Writes are disabled. Set ${surface.envPrefix}_ALLOW_WRITES=1 to enable the mutating tools.`);
+	}
+};
+/** A read-only index could not be opened, so the file lane is unavailable. */
+var IndexUnavailableError = class extends AppleAutomationError {
+	name = "IndexUnavailableError";
+};
+/** The store's schema is not the one we know how to read. */
+var SchemaDriftError = class extends AppleAutomationError {
+	name = "SchemaDriftError";
+};
+/** The server is not running on macOS, or osascript is missing. */
+var PlatformError = class extends AppleAutomationError {
+	name = "PlatformError";
+};
+/** osascript exited 0 but did not produce the JSON envelope we require. */
+var ProtocolError = class extends AppleAutomationError {
+	name = "ProtocolError";
+};
+/** A local precondition failed before anything was sent to the app. */
+var PreconditionError = class extends AppleAutomationError {
+	name = "PreconditionError";
+};
+/**
+* A date argument could not be read.
+*
+* Refusing is the whole point. The alternative — which is what Mail, Messages
+* and Notes did — is `Date.parse` returning `NaN`, node:sqlite binding it as
+* `NULL`, and the query matching nothing: an empty result that looks like an
+* answer. The message lists the accepted forms because the caller is usually a
+* model that guessed, and the fix is to show it the grammar.
+*/
+var InvalidDateError = class extends AppleAutomationError {
+	name = "InvalidDateError";
+	constructor(field, raw, reason) {
+		super(`Could not read ${field} from ${JSON.stringify(raw)}: ${reason}. Accepted: an ISO-8601 date "2026-08-20" (a whole day, local) or date-time "2026-08-20T09:00" (local unless it carries an offset), a signed offset like "+2d", "-3h", "+45m", "+1w", "today", "yesterday", "tomorrow 09:00", "next monday" or "last friday".`, {
+			field,
+			raw
+		});
+	}
+};
+//#endregion
+//#region src/ax.ts
+/**
+* Borrowing the app's Accessibility driver.
+*
+* ## Why this exists at all
+*
+* `AXUIElementCopyAttributeValue` reads an attribute in **0.202 ms**. Reaching
+* the same attribute through `osascript` + JXA + System Events costs **47.4 ms**
+* — a 234x difference that is entirely transport, measured both ways on one
+* machine in `docs/desktop.md`. Every Accessibility number this repo recorded
+* before that document was taken through System Events, which is why the lane
+* was closed three times on figures that were pricing the wrong thing.
+*
+* The native call cannot be made from here. Node has no binding for it, and
+* more importantly the grant does not belong to node: TCC attaches
+* Accessibility to the **responsible GUI ancestor**, so it is Cupertino.app
+* that holds it. Hence a channel rather than a port — the app already runs the
+* driver, and `ServerHost` will lend it for one bundle id.
+*
+* ## The second grant this removes, which matters more than the speed
+*
+* Driving a UI through System Events needs Automation-to-System-Events **on top
+* of** Accessibility. Two grants, given in two different System Settings panes,
+* to reach one window. The native driver needs the first and not the second.
+*
+* ## Absence is the fallback, not an error
+*
+* `CUPERTINO_AX_SOCKET` and `CUPERTINO_AX_FOR` are set by `ServerLocator` and by
+* nothing else. A package installed from npm and run by hand has neither, and
+* that is the supported case: these are published artifacts that must work with
+* no app on the machine. `open()` returns null there, and the caller keeps
+* whatever lane it had. It never throws to say "no app".
+*
+* ## Lazy, deliberately
+*
+* Nothing connects at construction. `SurfaceCatalog` probes servers to learn
+* what they register, and a probe that opened a socket would make every capability
+* scan depend on the host being ready to answer one.
+*/
+/** The handshake `ServerHost` expects, and the reply it sends back. */
+const PROTOCOL = "cupertino/1";
+const LENT_SURFACE = "desktop";
+const OK = "ok";
+/**
+* How long one call may take.
+*
+* A walk carries its own five-second budget and the AX messaging timeout is two
+* seconds per element, so the ceiling that matters is the app's, not this one's.
+* This is only here so a host that stopped answering fails rather than hanging a
+* tool call forever.
+*/
+const CALL_TIMEOUT_MS = 3e4;
+/**
+* The app is there and said no, or stopped answering.
+*
+* Distinct from the null `openAxChannel` returns, which means there is no app
+* to ask — see the note there on why those two must not collapse.
+*/
+var AxChannelError = class extends AppleAutomationError {
+	name = "AxChannelError";
+	constructor(surface, message) {
+		super(`${surface.appName}: ${message}`, { surface: surface.appName });
+	}
+};
+/** What the host told us, when it refused the handshake. */
+const refusal = (line) => line.startsWith("err ") ? line.slice(4) : `unexpected handshake reply '${line}'`;
+/**
+* Open the channel, or return null when this server is not hosted by the app.
+*
+* Null and a throw are different answers and the difference is the whole
+* contract: null means "there is no app here, use your other lane", a throw
+* means "there is an app and it said no", which a caller must report rather
+* than paper over.
+*/
+const openAxChannel = (surface, env = process.env) => {
+	const socketPath = env.CUPERTINO_AX_SOCKET?.trim();
+	const identity = env.CUPERTINO_AX_FOR?.trim();
+	if (!socketPath || !identity) return null;
+	let socket = null;
+	let pending = Promise.resolve();
+	let nextId = 1;
+	const connectOnce = () => new Promise((resolve, reject) => {
+		const s = connect(socketPath);
+		let buffer = "";
+		const onError = (error) => {
+			s.destroy();
+			reject(new AxChannelError(surface, `cannot reach Cupertino: ${error.message}`));
+		};
+		s.once("error", onError);
+		s.setEncoding("utf8");
+		const onData = (chunk) => {
+			buffer += chunk;
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) return;
+			const line = buffer.slice(0, newline).trim();
+			s.off("data", onData);
+			s.off("error", onError);
+			if (line !== OK) {
+				s.destroy();
+				reject(new AxChannelError(surface, refusal(line)));
+				return;
+			}
+			resolve(s);
+		};
+		s.on("data", onData);
+		s.write(`${PROTOCOL} ${LENT_SURFACE} for=${identity}\n`);
+	});
+	const request = async (payload) => {
+		socket ??= await connectOnce();
+		const live = socket;
+		const id = nextId++;
+		const line = `${JSON.stringify({
+			jsonrpc: "2.0",
+			id,
+			method: "tools/call",
+			params: {
+				name: payload.tool,
+				arguments: payload.args
+			}
+		})}\n`;
+		return new Promise((resolve, reject) => {
+			let buffer = "";
+			const timer = setTimeout(() => {
+				cleanup();
+				reject(new AxChannelError(surface, `${payload.tool} did not answer in ${CALL_TIMEOUT_MS}ms`));
+			}, CALL_TIMEOUT_MS);
+			const cleanup = () => {
+				clearTimeout(timer);
+				live.off("data", onData);
+				live.off("error", onError);
+				live.off("close", onClose);
+			};
+			const onError = (error) => {
+				cleanup();
+				reject(new AxChannelError(surface, `${payload.tool} failed: ${error.message}`));
+			};
+			const onClose = () => {
+				cleanup();
+				socket = null;
+				reject(new AxChannelError(surface, `Cupertino closed the connection during ${payload.tool}`));
+			};
+			const onData = (chunk) => {
+				buffer += chunk;
+				const newline = buffer.indexOf("\n");
+				if (newline < 0) return;
+				const raw = buffer.slice(0, newline);
+				cleanup();
+				let message;
+				try {
+					message = JSON.parse(raw);
+				} catch {
+					reject(new AxChannelError(surface, `unparseable reply to ${payload.tool}`));
+					return;
+				}
+				if (message.error) {
+					reject(new AxChannelError(surface, message.error.message ?? "unknown error"));
+					return;
+				}
+				const text = message.result?.content?.[0]?.text;
+				if (text === void 0) {
+					reject(new AxChannelError(surface, `empty reply to ${payload.tool}`));
+					return;
+				}
+				if (message.result?.isError === true) {
+					reject(new AxChannelError(surface, `${payload.tool}: ${text}`));
+					return;
+				}
+				try {
+					resolve(JSON.parse(text));
+				} catch {
+					resolve(text);
+				}
+			};
+			live.on("data", onData);
+			live.once("error", onError);
+			live.once("close", onClose);
+			live.write(line);
+		});
+	};
+	return {
+		call(payload) {
+			const result = pending.then(() => request(payload));
+			pending = result.then(() => void 0, () => void 0);
+			return result;
+		},
+		close() {
+			socket?.destroy();
+			socket = null;
+		}
+	};
+};
+/**
+* Start watching. `check()` answers for the span since this call.
+*
+* Returns null from `check()` when the question could not be asked at all,
+* which is not the same as "undisturbed" and must not be reported as it.
+*/
+const watchInterference = (channel) => {
+	const started = Date.now();
+	return { async check() {
+		const elapsedSeconds = (Date.now() - started) / 1e3;
+		try {
+			const secondsSinceInput = (await channel.call({
+				tool: "apple_desktop_user_activity",
+				args: {}
+			})).secondsSinceInput;
+			if (typeof secondsSinceInput !== "number") return null;
+			return {
+				disturbed: secondsSinceInput < elapsedSeconds,
+				secondsSinceInput,
+				elapsedSeconds
+			};
+		} catch {
+			return null;
+		}
+	} };
+};
+/**
+* The sentence to append to a failure, or "" when nothing useful can be said.
+*
+* Deliberately says nothing when the machine was quiet: a failure that reads
+* "nobody touched it" invites the reader to stop looking, and the point of this
+* is to send them to the RIGHT place rather than to reassure them.
+*/
+const interferenceNote = (found) => {
+	if (!found?.disturbed) return "";
+	return ` Someone used this Mac ${found.secondsSinceInput.toFixed(1)}s ago, during the ${found.elapsedSeconds.toFixed(1)}s this took — a keystroke or click lands wherever the focus is, so that alone can explain this. Retry with the machine idle before looking further.`;
+};
+//#endregion
 //#region src/build-info.ts
 /**
 * Read a package's own name and version at startup, so they are always accurate
@@ -521,74 +839,216 @@ const parseConfig = (schema, raw) => {
 	return parsed.data;
 };
 //#endregion
-//#region src/errors.ts
-/** Base class so `toFailure` can carry structured detail through in one branch. */
-var AppleAutomationError = class extends Error {
-	name = "AppleAutomationError";
-	details;
-	constructor(message, details) {
-		super(message);
-		this.details = details;
-	}
+//#region src/dates.ts
+/**
+* The one grammar every surface reads its date arguments with.
+*
+* ## Why it is here
+*
+* This shipped as three copies. Reminders wrote it, Calendar repeated it
+* verbatim, and Safari repeated it again with signed offsets and `yesterday`
+* added — that third copy's header says outright that three is the trigger for
+* hoisting and that the copies had already diverged. Meanwhile Mail, Messages
+* and Notes never got a grammar at all: they called `Date.parse` or
+* `new Date()` directly, which is where the bugs were.
+*
+* They were not small bugs, and they were all the same shape — a date argument
+* that produced a confident, plausible, wrong answer:
+*
+*   - `Date.parse("last week")` is `NaN`, node:sqlite binds `NaN` as `NULL`,
+*     and `date_received >= NULL` matches nothing. A model that wrote a date in
+*     words got zero results and no error.
+*   - `new Date("2026-08-20")` is UTC midnight but `new Date("2026-08-20T00:00")`
+*     is LOCAL midnight, so two spellings a tool description treated as the
+*     same thing bounded a query an hour or five apart.
+*   - `"2026-02-30T09:00"` silently became 2 March, because the rollover guard
+*     existed on the date branch and not on the date-time one.
+*
+* ## The rule
+*
+* 1. `YYYY-MM-DD` names a **local calendar day**. As a start bound it is local
+*    00:00 of that day; as an end bound it is local 00:00 of the NEXT day, and
+*    every consumer compares with `<`. So `to: "2026-08-20"` includes all of
+*    the 20th and nothing of the 21st. Resolving it to midnight of the same day
+*    is how an end bound quietly excludes the day it names.
+* 2. `YYYY-MM-DD[T ]HH:MM[:SS]` is local wall-clock; with `Z` or `±HH:MM` it is
+*    the instant named. A timed bound is used as given, and is exclusive at the
+*    end edge like everything else.
+* 3. Relative forms: `±N m|h|d|w`, `today` / `yesterday` / `tomorrow` with an
+*    optional `HH:MM`, and `next|last <weekday>`. Days and weeks are calendar
+*    arithmetic; hours and minutes are elapsed time. That split is not
+*    cosmetic — reversing it drifts every bound by an hour twice a year.
+* 4. Anything else, an empty string, or an instant that does not exist
+*    (`2026-02-30`, `T25:00`, `T09:60`) throws `InvalidDateError`. **Nothing
+*    here ever returns `NaN`**, because a `NaN` reaches SQLite as `NULL` and a
+*    `NULL` bound is an empty result rather than a complaint.
+*
+* The forward-only surfaces inherit the backward forms too. A reminder cannot
+* be due `-7d`, but accepting it costs nothing and refusing it in one surface
+* while accepting it in another is exactly the drift this file replaces.
+*/
+const DAY_NAMES = [
+	"sunday",
+	"monday",
+	"tuesday",
+	"wednesday",
+	"thursday",
+	"friday",
+	"saturday"
+];
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_DATETIME = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?(Z|[+-]\d{2}:?\d{2})?$/;
+const OFFSET = /^([+-])(\d+)\s*(m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days|w|week|weeks)$/;
+const DAY_WORD = /^(today|tomorrow|yesterday)(?:\s+(\d{1,2}):(\d{2}))?$/;
+const RELATIVE_DAY = /^(next|last)\s+([a-z]+)(?:\s+(\d{1,2}):(\d{2}))?$/;
+/** `+02:00` / `-05:00` / `Z` for a given instant, in the system zone. */
+const offsetOf = (d) => {
+	const mins = -d.getTimezoneOffset();
+	if (mins === 0) return "Z";
+	const sign = mins < 0 ? "-" : "+";
+	const abs = Math.abs(mins);
+	return `${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
 };
-/** The host process may not send Apple Events to the app (osascript -1743). */
-var TccDeniedError = class extends AppleAutomationError {
-	name = "TccDeniedError";
-	constructor(surface) {
-		super(`Not authorized to control ${surface.appName}. Grant it in System Settings > Privacy & Security > Automation > (the app running this server) > ${surface.appName}, then restart the server. If no entry appears, the first attempt was denied before the prompt could be answered — run \`tccutil reset AppleEvents\` and try again.`);
-	}
+const pad = (n, w = 2) => String(n).padStart(w, "0");
+/**
+* Local wall-clock time rendered with its offset.
+*
+* Deliberately not `toISOString()`, which converts to UTC and would report a
+* 09:00 bound as `07:00Z` — correct as an instant, but unreadable in a tool
+* result whose purpose is confirming what the caller asked for.
+*/
+const toLocalIso = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}${offsetOf(d)}`;
+/** Local midnight on the given calendar day. */
+const startOfLocalDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate(), 0, 0, 0, 0);
+/**
+* The last representable instant of the given calendar day, local.
+*
+* Kept for surfaces that genuinely want an inclusive edge. It is NOT what an
+* end bound resolves to — see `parseBound`.
+*/
+const endOfLocalDay = (d) => new Date(d.getFullYear(), d.getMonth(), d.getDate(), 23, 59, 59, 999);
+/** Calendar-aware day arithmetic: same wall-clock time, n days later. */
+const addLocalDays = (d, n) => {
+	const out = new Date(d.getTime());
+	out.setDate(out.getDate() + n);
+	return out;
 };
-/** The app is not running and the operation refuses to launch it. */
-var AppNotRunningError = class extends AppleAutomationError {
-	name = "AppNotRunningError";
-	constructor(surface) {
-		super(`${surface.appName} is not running. Read tools do not launch it, because launching it steals focus and can start a sync. Open ${surface.appName} and retry.`);
-	}
+const at = (day, hours, minutes) => new Date(day.getFullYear(), day.getMonth(), day.getDate(), hours, minutes, 0, 0);
+const isLeap = (y) => y % 4 === 0 && y % 100 !== 0 || y % 400 === 0;
+const daysInMonth = (y, mo) => [
+	31,
+	isLeap(y) ? 29 : 28,
+	31,
+	30,
+	31,
+	30,
+	31,
+	31,
+	30,
+	31,
+	30,
+	31
+][mo - 1] ?? 0;
+/**
+* Reject an instant that does not exist, BEFORE building a Date from it.
+*
+* Checking afterwards does not work, for two reasons found the hard way. An
+* out-of-range hour rolls the DAY over, so `2026-08-20T25:00` comes back as the
+* 21st at 01:00 and a naive date comparison blames the day the caller got
+* right. And a zoned string does not answer `NaN` at all:
+* `new Date("2026-02-30T09:00Z")` is 2 March, so there is nothing to catch.
+*
+* Arithmetic on the components has neither problem and does not depend on the
+* zone. The order matters — time first, because that is what rolled the date.
+*/
+const assertReal = (field, text, y, mo, d, hh = 0, mm = 0, ss = 0) => {
+	if (hh > 23 || mm > 59 || ss > 59) throw new InvalidDateError(field, text, `${pad(hh)}:${pad(mm)} is not a time`);
+	if (mo < 1 || mo > 12) throw new InvalidDateError(field, text, `there is no month ${pad(mo)}`);
+	if (d < 1 || d > daysInMonth(y, mo)) throw new InvalidDateError(field, text, `there is no day ${pad(d)} in month ${pad(mo)}`);
 };
-/** The app was busy and refused the Apple Event (-1712). Retried once before surfacing. */
-var AppBusyError = class extends AppleAutomationError {
-	name = "AppBusyError";
-	constructor(surface) {
-		super(`${surface.appName} is busy (probably syncing) and did not answer in time. Retry in a few seconds.`);
+const result = (kind, when, raw) => ({
+	kind,
+	at: when,
+	iso: toLocalIso(when),
+	raw
+});
+/**
+* Parse one date argument.
+*
+* @param field Named in the error, so a failure says *which* argument was bad.
+* @param raw   The caller's string.
+* @param now   Injected for hermetic tests, mirroring `loadConfig(env)`.
+*/
+const parseDate = (field, raw, now = /* @__PURE__ */ new Date()) => {
+	const text = String(raw ?? "").trim();
+	if (!text) throw new InvalidDateError(field, String(raw), "it is empty");
+	const lower = text.toLowerCase();
+	const dt = ISO_DATETIME.exec(text);
+	if (dt) {
+		const [, y, mo, d, hh, mm, ss, zone] = dt;
+		assertReal(field, text, Number(y), Number(mo), Number(d), Number(hh), Number(mm), Number(ss ?? "0"));
+		const when = zone ? new Date(text.replace(" ", "T")) : new Date(Number(y), Number(mo) - 1, Number(d), Number(hh), Number(mm), Number(ss ?? "0"), 0);
+		if (Number.isNaN(when.getTime())) throw new InvalidDateError(field, text, "it is not a real date");
+		return result("timed", when, text);
 	}
-};
-/** osascript exceeded its budget and was killed. */
-var OsascriptTimeoutError = class extends AppleAutomationError {
-	name = "OsascriptTimeoutError";
-	constructor(timeoutMs, surface) {
-		super(`${surface.appName} did not answer within ${timeoutMs}ms. It may be mid-sync, or a permission prompt may be waiting on screen. Raise ${surface.envPrefix}_OSASCRIPT_TIMEOUT_MS if this is routine at your data size.`);
+	const only = ISO_DATE.exec(text);
+	if (only) {
+		const [, y, mo, d] = only;
+		assertReal(field, text, Number(y), Number(mo), Number(d));
+		const when = new Date(Number(y), Number(mo) - 1, Number(d), 0, 0, 0, 0);
+		if (Number.isNaN(when.getTime())) throw new InvalidDateError(field, text, "it is not a real date");
+		return result("allDay", when, text);
+	}
+	const off = OFFSET.exec(lower);
+	if (off) {
+		const sign = off[1] === "-" ? -1 : 1;
+		const n = Number(off[2]) * sign;
+		const unit = String(off[3]);
+		if (!Number.isFinite(n)) throw new InvalidDateError(field, text, "the amount is not a number");
+		if (unit.startsWith("d")) return result("timed", addLocalDays(now, n), text);
+		if (unit.startsWith("w")) return result("timed", addLocalDays(now, n * 7), text);
+		const ms = unit.startsWith("h") ? n * 36e5 : n * 6e4;
+		return result("timed", new Date(now.getTime() + ms), text);
 	}
+	const word = DAY_WORD.exec(lower);
+	if (word) {
+		const shift = word[1] === "tomorrow" ? 1 : word[1] === "yesterday" ? -1 : 0;
+		const day = addLocalDays(now, shift);
+		if (word[2] === void 0) return result("allDay", startOfLocalDay(day), text);
+		const [hh, mm] = [Number(word[2]), Number(word[3])];
+		if (hh > 23 || mm > 59) throw new InvalidDateError(field, text, `${hh}:${word[3]} is not a time`);
+		return result("timed", at(day, hh, mm), text);
+	}
+	const rel = RELATIVE_DAY.exec(lower);
+	if (rel) {
+		const idx = DAY_NAMES.findIndex((n) => n === rel[2] || n.slice(0, 3) === rel[2]);
+		if (idx === -1) throw new InvalidDateError(field, text, `"${rel[2]}" is not a day of the week`);
+		const delta = rel[1] === "next" ? (idx - now.getDay() + 7) % 7 || 7 : -((now.getDay() - idx + 7) % 7 || 7);
+		const day = addLocalDays(now, delta);
+		if (rel[3] === void 0) return result("allDay", startOfLocalDay(day), text);
+		const [hh, mm] = [Number(rel[3]), Number(rel[4])];
+		if (hh > 23 || mm > 59) throw new InvalidDateError(field, text, `${hh}:${rel[4]} is not a time`);
+		return result("timed", at(day, hh, mm), text);
+	}
+	throw new InvalidDateError(field, text, "it matches none of the accepted forms");
 };
 /**
-* A write was attempted while writes are disabled. Under the house pattern write
-* tools are not registered at all when `allowWrites` is off, so this is a
-* belt-and-braces guard for the library surface, not a path tools can reach.
+* Parse a bound for a range filter.
+*
+* A bare day names the WHOLE day, so which instant it resolves to depends on
+* which edge it is. The start edge is that day's local midnight. The end edge
+* is the NEXT day's local midnight, and every caller compares with `<` — which
+* makes the bound exclusive and the named day fully included.
+*
+* The alternative, 23:59:59.999, was what two of the three copies did, and it
+* is wrong twice: it drops the last millisecond of the day, and more to the
+* point it invites the `<=` that then drops the whole day when somebody writes
+* midnight instead.
 */
-var WritesDisabledError = class extends AppleAutomationError {
-	name = "WritesDisabledError";
-	constructor(surface) {
-		super(`Writes are disabled. Set ${surface.envPrefix}_ALLOW_WRITES=1 to enable the mutating tools.`);
-	}
-};
-/** A read-only index could not be opened, so the file lane is unavailable. */
-var IndexUnavailableError = class extends AppleAutomationError {
-	name = "IndexUnavailableError";
-};
-/** The store's schema is not the one we know how to read. */
-var SchemaDriftError = class extends AppleAutomationError {
-	name = "SchemaDriftError";
-};
-/** The server is not running on macOS, or osascript is missing. */
-var PlatformError = class extends AppleAutomationError {
-	name = "PlatformError";
-};
-/** osascript exited 0 but did not produce the JSON envelope we require. */
-var ProtocolError = class extends AppleAutomationError {
-	name = "ProtocolError";
-};
-/** A local precondition failed before anything was sent to the app. */
-var PreconditionError = class extends AppleAutomationError {
-	name = "PreconditionError";
+const parseBound = (field, raw, edge, now = /* @__PURE__ */ new Date()) => {
+	const parsed = parseDate(field, raw, now);
+	if (parsed.kind !== "allDay") return parsed.at;
+	return edge === "end" ? startOfLocalDay(addLocalDays(parsed.at, 1)) : startOfLocalDay(parsed.at);
 };
 //#endregion
 //#region src/tools.ts
@@ -1476,28 +1936,34 @@ const openReadOnly = (path, mode, opts = {}) => {
 	if (mode === "off") throw new IndexUnavailableError(`The index lane is disabled${opts.envVar ? ` (${opts.envVar}=off)` : ""}.`);
 	const attempts = mode === "auto" ? ["ro", "immutable"] : [mode === "ro" ? "ro" : "immutable"];
 	let lastError = null;
-	for (const attempt of attempts) try {
-		const uri = toFileUri(path, attempt === "ro" ? "mode=ro" : "immutable=1");
-		const db = new DatabaseSync(uri, {
-			readOnly: true,
-			allowExtension: false
-		});
-		db.exec("PRAGMA query_only = 1");
-		const validated = opts.validate?.(db);
-		if (attempt === "immutable") opts.onFallback?.();
-		return {
-			db,
-			mode: attempt,
-			validated
-		};
-	} catch (err) {
-		if (opts.fatal?.(err)) throw err;
-		lastError = err;
+	for (const attempt of attempts) {
+		let db;
+		try {
+			const uri = toFileUri(path, attempt === "ro" ? "mode=ro" : "immutable=1");
+			db = new DatabaseSync(uri, {
+				readOnly: true,
+				allowExtension: false
+			});
+			db.exec("PRAGMA query_only = 1");
+			const validated = opts.validate?.(db);
+			if (attempt === "immutable") opts.onFallback?.();
+			return {
+				db,
+				mode: attempt,
+				validated
+			};
+		} catch (err) {
+			try {
+				db?.close();
+			} catch {}
+			if (opts.fatal?.(err)) throw err;
+			lastError = err;
+		}
 	}
 	const message = lastError instanceof Error ? lastError.message : String(lastError);
 	throw new IndexUnavailableError(`Could not open ${opts.label ?? path} at ${path}: ${message}.${opts.hint ? ` ${opts.hint}` : ""}`);
 };
 //#endregion
-export { AppBusyError, AppNotRunningError, AppleAutomationError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, RESOURCE_SCHEME, SchemaDriftError, TccDeniedError, WritesDisabledError, assertStaticScript, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, limitArg, mapOsaError, ok, okText, openReadOnly, parseBool, parseConfig, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, surfaceUri, tableMap, toFailure, toFileUri, trimToolListing, trimmed, withBusyRetry, withLazyTools, withTrimmedListing, wrap, wrapResult };
+export { AppBusyError, AppNotRunningError, AppleAutomationError, AxChannelError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, InvalidDateError, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, RESOURCE_SCHEME, SchemaDriftError, TccDeniedError, WritesDisabledError, addLocalDays, assertStaticScript, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, endOfLocalDay, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, interferenceNote, limitArg, mapOsaError, ok, okText, openAxChannel, openReadOnly, parseBool, parseBound, parseConfig, parseDate, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, startOfLocalDay, surfaceUri, tableMap, toFailure, toFileUri, toLocalIso, trimToolListing, trimmed, watchInterference, withBusyRetry, withLazyTools, withTrimmedListing, wrap, wrapResult };
 
 //# sourceMappingURL=index.js.map