@mgcrea/mcp-apple-maps 1.37.1 → 1.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -28,25 +28,33 @@ from Maps' Core Data store.
28
28
 
29
29
  ## What it writes
30
30
 
31
- Only with `APPLE_MAPS_ALLOW_WRITES=1`. Both are unregistered rather than refused when it is off, so a
32
- client that has not opted in is never told they exist.
33
-
34
- | Tool | What |
35
- | ---------------------------- | --------------------------------------------------------- |
36
- | `apple_maps_add_favorite` | save a place as a favourite, seeding it through `maps://` |
37
- | `apple_maps_remove_favorite` | drop a favourite row |
38
-
39
- Three more press controls on a place card through Accessibility rather than writing SQL, and are
40
- registered only when Cupertino.app hosts this server: the grant belongs to the app, so a package
41
- run from npm has no way to reach them and is never told they exist.
42
-
43
- | Tool | What |
44
- | ------------------------------- | ---------------------------------------------------------- |
45
- | `apple_maps_save_place` | add a place to the Places library (not the same as Pinned) |
46
- | `apple_maps_remove_saved_place` | remove a place from the Places library |
47
- | `apple_maps_add_place_to_guide` | file a place in an existing Guide; Maps cannot confirm it |
48
-
49
- Each opens Maps, brings its window forward and leaves the place in your Recents.
31
+ **Run from npm, nothing.** This package only reads Maps: with no Cupertino hosting it, it registers
32
+ no write tool, whatever `APPLE_MAPS_ALLOW_WRITES` says. Until 2026-11-11 it wrote favourites as SQL
33
+ straight into the store. The watch that day found those inserts never mirrored to iCloud, and saw
34
+ Maps turn favourites like them into saved places, so that route was removed
35
+ ([docs/maps.md](../../docs/maps.md#what-maps-changes-watched-2026-11-11)).
36
+
37
+ **In [Cupertino](https://cupertino.mgcrea.io)**, with writes on, five tools save through Maps' own
38
+ Core Data model inside Cupertino.app, so each change is recorded the way a change made in Maps is.
39
+ The write tools are unregistered rather than refused when writes are off, so a client that has not
40
+ opted in is never told they exist.
41
+
42
+ | Tool | What |
43
+ | ------------------------------- | ---------------------------------------------------------------------------------------- |
44
+ | `apple_maps_add_favorite` | pin a place |
45
+ | `apple_maps_remove_favorite` | unpin a place, by ref; as in Maps, it stays in your library as a saved place |
46
+ | `apple_maps_save_place` | save a place to the library, in no Guide (not the same as Pinned) |
47
+ | `apple_maps_remove_saved_place` | remove a saved place, by ref |
48
+ | `apple_maps_add_place_to_guide` | file a saved place (by ref) or a new one (by name) in an existing Guide, read back after |
49
+
50
+ None of them brings Maps forward or presses anything. A place record can only be minted by Maps, so
51
+ unless the place is already in the store near the coordinate given, Maps resolves it from its name:
52
+ **it is left in your Recents**, and resolving it can take tens of seconds. Sync was measured on
53
+ macOS 27.2 (Maps model checksum `CaxhFkDDBEvVUHzx/wKUv4k+QehKTgcfEuPWR91+uhk=`), every tool on a
54
+ Mac and an iPhone on 2026-11-11: on that model a write reaches your other devices through iCloud
55
+ **even with Maps closed**, as Maps' background service uploads it, seen with one write made while
56
+ Maps was quit. On another Maps model version each answer's `sync` says sync is not yet measured,
57
+ and the place should be checked on another device.
50
58
 
51
59
  ## What it does not do
52
60
 
@@ -54,13 +62,11 @@ It reads what is **saved on this Mac**. It does not search Apple's map of the wo
54
62
  address, give directions or compute a travel time. Those are network calls to Apple's services,
55
63
  not data on your disk.
56
64
 
57
- It writes only with `APPLE_MAPS_ALLOW_WRITES` set: favourites through the store, and the Places
58
- library and Guide membership through Maps' own interface. Everything else here is read-only. The store is mirrored to iCloud by `NSPersistentCloudKitContainer`, so a write is an edit
59
- to one replica of a synchronising object graph underneath a running app — a malformed row reaches
60
- every device on the account. That is why a place record is never fabricated: adding a favourite opens
61
- `maps://` so that Maps itself mints the record, and only then is it copied. **The place is left in
62
- your Recents whether or not you keep the favourite**, and resolving it over the network can take tens
63
- of seconds.
65
+ It writes only in Cupertino, with writes on: pins, the Places library and Guide membership.
66
+ Everything else here is read-only. The store is mirrored to iCloud by
67
+ `NSPersistentCloudKitContainer`, so a write is an edit to one replica of a synchronising object
68
+ graph underneath a running app. That is why a place record is never fabricated: Maps itself mints
69
+ it, and only then is it copied.
64
70
 
65
71
  ## Full Disk Access is mandatory
66
72
 
@@ -73,16 +79,17 @@ If a listing comes back empty, that means you have saved nothing of that kind. R
73
79
 
74
80
  ## Configuration
75
81
 
76
- | Variable | Default | What |
77
- | ---------------------------- | ---------- | --------------------------------------------------------- |
78
- | `APPLE_MAPS_STORE` | discovered | explicit store path, for tests and forensic copies |
79
- | `APPLE_MAPS_INDEX_MODE` | `auto` | `auto` / `ro` / `immutable` / `off` |
80
- | `APPLE_MAPS_MAX_RESULTS` | 50 | default result ceiling |
81
- | `APPLE_MAPS_SEED_TIMEOUT_MS` | 30000 | how long `add_favorite` waits for Maps to resolve a place |
82
- | `APPLE_MAPS_EXPOSE_PROMPTS` | on | register the prompt and `cupertino://maps/*` resources |
83
- | `APPLE_MAPS_DEBUG` | off | verbose logging on stderr |
84
-
85
- `APPLE_MAPS_ALLOW_WRITES` (off) registers the tools under [What it writes](#what-it-writes).
82
+ | Variable | Default | What |
83
+ | ---------------------------- | ---------- | ------------------------------------------------------ |
84
+ | `APPLE_MAPS_STORE` | discovered | explicit store path, for tests and forensic copies |
85
+ | `APPLE_MAPS_INDEX_MODE` | `auto` | `auto` / `ro` / `immutable` / `off` |
86
+ | `APPLE_MAPS_MAX_RESULTS` | 50 | default result ceiling |
87
+ | `APPLE_MAPS_SEED_TIMEOUT_MS` | 30000 | how long a write waits for Maps to resolve a place |
88
+ | `APPLE_MAPS_EXPOSE_PROMPTS` | on | register the prompt and `cupertino://maps/*` resources |
89
+ | `APPLE_MAPS_DEBUG` | off | verbose logging on stderr |
90
+
91
+ `APPLE_MAPS_ALLOW_WRITES` (off) registers the tools under [What it writes](#what-it-writes) when
92
+ Cupertino hosts this server. Run from npm it registers nothing.
86
93
 
87
94
  See [docs/maps.md](../../docs/maps.md) for the phase-0 measurements, including the three separate
88
95
  occasions on which this store was declared not to exist.
package/dist/cli.js CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { C as MAPS_SURFACE, N as BUILD_INFO, a as loadConfig, r as createServer } from "./server-C5JyIvr1.js";
2
+ import { C as MAPS_SURFACE, N as BUILD_INFO, a as loadConfig, r as createServer } from "./server-QidAKfSq.js";
3
3
  import { runStdioServer } from "@mgcrea/mcp-apple-core";
4
4
  //#region src/cli.ts
5
5
  const LOG_PREFIX = "apple-maps-mcp";
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { AppleAutomationError, AppleAutomationError as AppleMapsError, BuildInfo, CORE_DATA_EPOCH_OFFSET, Epoch, FileFacts, IndexUnavailableError, InterferenceWatch, Logger, ReadOnlyMode, SchemaDriftError, StoreFacts, SurfaceContext } from "@mgcrea/mcp-apple-core";
1
+ import { AppleAutomationError, AppleAutomationError as AppleMapsError, BuildInfo, CORE_DATA_EPOCH_OFFSET, Epoch, FileFacts, IndexUnavailableError, Logger, ReadOnlyMode, SchemaDriftError, StoreFacts, SurfaceContext } from "@mgcrea/mcp-apple-core";
2
2
  import { DatabaseSync } from "node:sqlite";
3
3
  import { z } from "zod";
4
4
  import { McpServer } from "@modelcontextprotocol/server";
@@ -94,13 +94,14 @@ declare const locateStore: (opts?: {
94
94
  * Configuration is environment-only — this server holds no secret at all. Its
95
95
  * access is the macOS permission the user granted, which is the whole point.
96
96
  *
97
- * `allowWrites` gates two mutating tools, and gates them harder than elsewhere.
98
- * Maps has no scripting dictionary and no registered App Intents, so a write is
99
- * SQL straight into a Core Data store that `NSPersistentCloudKitContainer`
100
- * mirrors — which means it reaches every device on the account, not just this
101
- * Mac. That was measured, along with the rule that keeps it safe: never
102
- * fabricate a place record, only ever copy one Maps wrote itself. See
103
- * `docs/maps.md` and `client/write.ts`.
97
+ * `allowWrites` gates the mutating tools, and only matters when Cupertino
98
+ * hosts this server. Maps has no scripting dictionary and no registered App
99
+ * Intents, so its one write route is Cupertino's store lane, which saves with
100
+ * Maps' own Core Data model; on macOS 27.2 those saves were measured on
101
+ * 2026-11-11 to reach an iPhone through iCloud. Run from npm there is no lane,
102
+ * and no write tool is registered whatever this says. The lane keeps one rule:
103
+ * never fabricate a place record, only ever copy one Maps wrote itself. See
104
+ * `docs/maps.md`.
104
105
  */
105
106
  declare const ConfigSchema: z.ZodObject<{
106
107
  allowWrites: z.ZodDefault<z.ZodBoolean>;
@@ -121,109 +122,16 @@ declare const ConfigSchema: z.ZodObject<{
121
122
  type Config = z.infer<typeof ConfigSchema>;
122
123
  declare const loadConfig: (env?: NodeJS.ProcessEnv) => Config;
123
124
  //#endregion
124
- //#region src/client/ax.d.ts
125
- type Guide = {
126
- name: string;
127
- places: number | null;
128
- };
129
- /** Injected so tests never shell out, matching `write.ts`'s `OpenUrl` seam. */
130
- type OpenUrl$1 = (url: string) => void;
125
+ //#region src/client/open-url.d.ts
131
126
  /**
132
- * How long to wait for a card, a sheet or a picker.
127
+ * How a place is opened in Maps, so Maps mints the place record a write copies.
133
128
  *
134
- * Overridable so a test can pin a "this never appeared" path without waiting for
135
- * it. Ten seconds because a place has to resolve over the network before its
136
- * card exists; sheets and pickers are local and get less.
129
+ * `maps://?q=<query>` goes through LaunchServices, not Apple Events and not
130
+ * Accessibility, and Maps resolves the place and files it in Recents with a
131
+ * full record attached (`place-source.ts`). Injected so tests never launch an
132
+ * application.
137
133
  */
138
- type Waits = {
139
- card: number;
140
- sheet: number;
141
- };
142
- declare class MapsAxLane {
143
- #private;
144
- private constructor();
145
- /** Null when this server is not hosted by Cupertino — see `core/src/ax.ts`. */
146
- static open(env?: NodeJS.ProcessEnv, openUrl?: OpenUrl$1, waits?: Partial<Waits>): MapsAxLane | null;
147
- close(): void;
148
- /** Start watching for someone using the Mac during a sequence. */
149
- watch(): InterferenceWatch;
150
- /**
151
- * Open a place and wait for its card.
152
- *
153
- * The combined `q=` and `ll=` form, because a coordinate positions the map and
154
- * a NAME selects a place — `write.ts` records the same thing for the same
155
- * reason.
156
- */
157
- openCard(place: {
158
- name: string;
159
- latitude: number;
160
- longitude: number;
161
- }): Promise<boolean>;
162
- /**
163
- * Is this place saved?
164
- *
165
- * Read off `AddButton`'s NAME, which is the state bit. `docs/desktop.md`
166
- * corrected itself on this: `FavoriteButton` reports identical attributes
167
- * either way, and the sibling carries `"Add"` versus `"Added"`.
168
- *
169
- * Localised, and that is a real limit rather than an oversight — there is no
170
- * unlocalised state anywhere on this card.
171
- */
172
- isSaved(): Promise<boolean | null>;
173
- /**
174
- * Save the open place into the Places library.
175
- *
176
- * Two presses, not one: `AddButton` raises a **"Name This Location"** sheet
177
- * and nothing is written until its `Save` is pressed. The sheet REPLACES the
178
- * window list — a full walk during it returns the sheet and nothing else — so
179
- * the card's elements are unreachable until it closes, and `Save` carries no
180
- * `AXIdentifier`, which is why it is addressed by name.
181
- */
182
- savePlace(): Promise<boolean>;
183
- /**
184
- * Remove the open place from the Places library.
185
- *
186
- * The menu item is `delete_from_places`, and it is only present when the place
187
- * IS saved — the same slot carries `add_to_places` when it is not. So its
188
- * absence is a state reading rather than a failure, and this reports which.
189
- */
190
- removePlace(): Promise<"removed" | "not-saved" | "no-menu">;
191
- /**
192
- * Every guide Maps knows about, read off its own picker.
193
- *
194
- * This is the authoritative list, and it is not the same as the store's:
195
- * `docs/desktop.md` found the picker showing a "Favorites" guide that
196
- * `apple_maps_list_collections` does not return. Read here as a side effect of
197
- * being on the way to a write, rather than as a tool of its own — reaching it
198
- * needs a place card, which needs a `maps://` open, which leaves a Recents
199
- * entry. That is too much side effect for something calling itself a read.
200
- *
201
- * Leaves the picker OPEN, because the caller is normally about to press a row.
202
- */
203
- openGuidePicker(): Promise<Guide[] | null>;
204
- /** Press one guide row, then Done. Returns false if no row matched. */
205
- chooseGuide(name: string): Promise<boolean>;
206
- /**
207
- * Re-open the card and read the state bit, which is the only way to verify.
208
- *
209
- * **A write closes the card.** Saving through the naming sheet dismisses the
210
- * whole place card and returns Maps to its main view, so reading `AddButton`
211
- * straight after a press finds nothing and reports "the card does not say it
212
- * is saved" — which is a sentence about the write having failed, when what
213
- * actually happened is that the thing being read went away.
214
- *
215
- * So verification re-opens the place first. That costs another `maps://`,
216
- * which is free in the sense that matters: the Recents entry this leaves was
217
- * already left by opening the card in the first place.
218
- */
219
- verifySaved(place: {
220
- name: string;
221
- latitude: number;
222
- longitude: number;
223
- }): Promise<boolean | null>;
224
- /** Abandon the picker without filing anything. */
225
- cancelGuidePicker(): Promise<void>;
226
- }
134
+ type OpenUrl = (url: string) => void | Promise<void>;
227
135
  //#endregion
228
136
  //#region src/client/store.d.ts
229
137
  type FieldMap = {
@@ -403,6 +311,182 @@ declare const openStore: (opts: {
403
311
  hint?: string;
404
312
  }) => MapsStore;
405
313
  //#endregion
314
+ //#region src/client/place-source.d.ts
315
+ /**
316
+ * Finding a place record for the store lane, without writing anything.
317
+ *
318
+ * The store lane saves through Maps' own Core Data model, and it can only COPY
319
+ * a place record (`ZMIXINMAPITEM.ZMAPITEMSTORAGE`) that Maps minted: the record
320
+ * is a GEO protobuf of one to four kilobytes that nobody here can generate, and
321
+ * on the measured model the lane's saves reach the account's other devices, so
322
+ * a fabricated record would go with them. `docs/maps.md` has the measurements.
323
+ * So before the lane is asked to write, this finds a record to copy and names
324
+ * the item that OWNS it, by that item's `ZIDENTIFIER`, because the lane fetches
325
+ * through the model by uuid, not by row id.
326
+ *
327
+ * Two ways to get one, in order, both kept from the SQL route this package ran
328
+ * until 2026-11-11:
329
+ *
330
+ * 1. A record already in the store within about a metre of the coordinate,
331
+ * owned by a favourite, a saved place or a recent. Costs nothing.
332
+ * 2. Seeding: open `maps://?q=<query>` and poll Recents above a watermark for
333
+ * the record Maps files there, refused when a second place lands there
334
+ * meanwhile. Leaves a Recents entry, which is why the first way is always
335
+ * tried first.
336
+ *
337
+ * Every connection here is read-only, and none is held across the seed: Maps is
338
+ * being asked to write the very row being waited for.
339
+ */
340
+ /** The owning item's kind, as the app's Maps writer spells its `SourceKind`. */
341
+ type SourceKind = "favorite" | "savedPlace" | "recent";
342
+ type PlaceSource = {
343
+ kind: SourceKind;
344
+ /** The owning item's `ZIDENTIFIER`, as a lowercase dashed uuid. */
345
+ id: string;
346
+ /** The record's own coordinate, which is Maps' canonical one. */
347
+ latitude: number;
348
+ longitude: number;
349
+ /** True when Maps had to be asked to resolve the place, leaving a Recents entry. */
350
+ seeded: boolean;
351
+ };
352
+ /**
353
+ * A favourite or saved place as it stands in the store, for a tool's answer.
354
+ *
355
+ * The name is the label when the user set one, else the place's own name, as
356
+ * the read tools render it. The coordinate is the item's, else its map
357
+ * item's: a field the store does not hold is null, never the caller's guess.
358
+ */
359
+ type StoredPlace = {
360
+ id: string;
361
+ name: string | null;
362
+ latitude: number | null;
363
+ longitude: number | null;
364
+ };
365
+ declare class PlaceSourceFinder {
366
+ #private;
367
+ constructor(opts: {
368
+ storePath: string;
369
+ openUrl?: OpenUrl;
370
+ seedTimeoutMs?: number;
371
+ });
372
+ /**
373
+ * Read back a favourite or saved place by the identifier the lane answered
374
+ * with, so a tool reports the item as it stands rather than what was asked
375
+ * for. Null when no such row is in the store (yet), or `id` is not a uuid.
376
+ */
377
+ describe(kind: "favorite" | "collection-item", id: string): StoredPlace | null;
378
+ /** An existing favourite for this place. Idempotence for `add_favorite`. */
379
+ existingFavorite(q: {
380
+ latitude: number;
381
+ longitude: number;
382
+ name?: string;
383
+ }): StoredPlace | null;
384
+ /** An existing saved place (a `CollectionPlaceItem`) for this place. */
385
+ existingSavedPlace(q: {
386
+ latitude: number;
387
+ longitude: number;
388
+ name?: string;
389
+ }): StoredPlace | null;
390
+ /**
391
+ * A place record for `query`: one already in the store near the coordinate,
392
+ * else one Maps mints on being asked. Refuses a resolution more than ~250 m
393
+ * from the coordinate given, and a seed that produces nothing in time.
394
+ *
395
+ * Async because the seed can take thirty seconds, and a blocking wait would
396
+ * leave this single-threaded stdio server unable to answer anything.
397
+ */
398
+ find(q: {
399
+ query: string;
400
+ latitude?: number;
401
+ longitude?: number;
402
+ }): Promise<PlaceSource>;
403
+ /**
404
+ * The `ZIDENTIFIER` of the row a read tool's ref names, or null when the row
405
+ * is not there or has no identifier — a row-id-only ref the lane, which
406
+ * fetches by uuid, cannot be given.
407
+ */
408
+ identifierOf(kind: "favorite" | "collection-item" | "history", key: EntityKey): string | null;
409
+ }
410
+ //#endregion
411
+ //#region src/client/lane.d.ts
412
+ /** What the app answers after one save. `changed` is empty when there was nothing to do. */
413
+ type LaneWrite = {
414
+ /** The item written, or the one that already stood there: a dashed uuid. */
415
+ id: string;
416
+ changed: string[];
417
+ /** False when the item already existed and was returned unchanged. */
418
+ created: boolean;
419
+ /** `fileInGuide` only: whether the read-back found the place in the Guide. */
420
+ filed?: boolean;
421
+ modelVersion: string | null;
422
+ /** True only on a Maps model whose iCloud upload was measured. */
423
+ syncMeasured: boolean;
424
+ };
425
+ /** Whether the app can write this Mac's Maps store, and why not when it cannot. */
426
+ type LaneStatus = {
427
+ compatible: boolean;
428
+ modelVersion: string | null;
429
+ syncMeasured: boolean;
430
+ refusal: string | null;
431
+ };
432
+ /** Where the place record to copy comes from: an item Maps wrote, by its identifier. */
433
+ type PlaceFrom = {
434
+ source: SourceKind;
435
+ sourceId: string;
436
+ /**
437
+ * What the caller searched Maps for. The app shows it as the place's name
438
+ * only when the source has none of its own (a recent), until a device
439
+ * refreshes the place; it never becomes a label.
440
+ */
441
+ query: string;
442
+ /** The caller's own label, only when they gave one: the app saves it as `customName`. */
443
+ name?: string | undefined;
444
+ /** The caller's coordinate, when given: the app refuses a record far from it. */
445
+ near?: {
446
+ latitude: number;
447
+ longitude: number;
448
+ } | undefined;
449
+ };
450
+ /**
451
+ * Maps' writes, saved by Cupertino.app through Core Data with Maps' own model,
452
+ * so they are recorded in persistent history like a change made in the app.
453
+ *
454
+ * The app does the work and validates every argument; this side only names the
455
+ * method and checks the answer has the shape the tools report. A reply of
456
+ * another shape is a `StoreLaneError` with reason `protocol`, the reason core
457
+ * uses for a reply it cannot read. The same lane as Voice Memos'
458
+ * (`packages/voice-memos/src/client/lane.ts`), on surface `maps`.
459
+ */
460
+ declare class MapsLane {
461
+ #private;
462
+ private constructor();
463
+ /**
464
+ * Null when this server is not hosted by Cupertino: see `core/src/store-lane.ts`.
465
+ *
466
+ * Opening connects nothing. Cupertino spawns the server with the lane env just
467
+ * to list its tools, and that listing must never wait on the app.
468
+ */
469
+ static open(env?: NodeJS.ProcessEnv): MapsLane | null;
470
+ close(): void;
471
+ /** A favourite with its own copy of the source's place record. */
472
+ addFavorite(p: PlaceFrom): Promise<LaneWrite>;
473
+ removeFavorite(id: string): Promise<LaneWrite>;
474
+ /** A saved place in no Guide, with its own copy of the source's place record. */
475
+ savePlace(p: PlaceFrom): Promise<LaneWrite>;
476
+ removeSavedPlace(id: string): Promise<LaneWrite>;
477
+ /**
478
+ * File a saved place in a Guide: one already saved, by `placeId`, or one to
479
+ * save first from a source, which the app saves and files in one save.
480
+ */
481
+ fileInGuide(p: {
482
+ guide: string;
483
+ placeId: string;
484
+ } | ({
485
+ guide: string;
486
+ } & PlaceFrom)): Promise<LaneWrite>;
487
+ status(): Promise<LaneStatus>;
488
+ }
489
+ //#endregion
406
490
  //#region src/client/ref.d.ts
407
491
  /**
408
492
  * Refs for places and collections.
@@ -472,73 +556,6 @@ declare const decodePlaceRef: (raw: string) => {
472
556
  };
473
557
  declare const decodeCollectionRef: (raw: string) => EntityKey;
474
558
  //#endregion
475
- //#region src/client/write.d.ts
476
- /** Injected so tests never launch an application. */
477
- type OpenUrl = (url: string) => void | Promise<void>;
478
- type AddFavoriteInput = {
479
- /** What to search for. A name; a bare coordinate does NOT open a place card. */
480
- query: string;
481
- latitude?: number | undefined;
482
- longitude?: number | undefined;
483
- /** The label to store. Defaults to `query`. */
484
- name?: string | undefined;
485
- };
486
- type AddFavoriteResult = {
487
- rowId: number;
488
- uuid: string;
489
- name: string | null;
490
- latitude: number | null;
491
- longitude: number | null;
492
- /** False when an equivalent favourite already existed and was returned as-is. */
493
- created: boolean;
494
- /** True when Maps had to be asked to resolve the place, leaving a Recents entry. */
495
- seeded: boolean;
496
- };
497
- declare class MapsWriter {
498
- #private;
499
- constructor(opts: {
500
- storePath: string;
501
- openUrl?: OpenUrl;
502
- seedTimeoutMs?: number;
503
- });
504
- /**
505
- * Add a favourite, in three phases with a connection open for as little of it
506
- * as possible.
507
- *
508
- * THE PHASES ARE THE POINT. A first version opened one read-write handle at the
509
- * top and held it across the whole seed — including the wait for Maps to
510
- * resolve a place, which can run to tens of seconds. That hung: Maps is being
511
- * asked to WRITE the very record being waited for, into a store this process is
512
- * holding open for writing. Whatever the precise interaction, the shape was a
513
- * departure from the sequence that had been proven by hand, and the proven
514
- * sequence never holds a write handle while waiting on the app.
515
- *
516
- * 1. READ — look for an existing favourite and an existing place record.
517
- * 2. SEED — ask Maps to mint a record, holding NO connection at all, and
518
- * poll with a short-lived read-only handle each time.
519
- * 3. WRITE — open read-write, insert, close.
520
- */
521
- /**
522
- * Async because the seed can take THIRTY SECONDS.
523
- *
524
- * When the place is not already in the store this asks Maps to mint it
525
- * through the URL scheme and then polls for the row to appear. That poll used
526
- * `Atomics.wait`, which blocks the thread — and this server is single
527
- * threaded, so for the whole seed it answered nothing at all: not a ping, not
528
- * a cancellation, not another tool call. A sleep that yields costs the same
529
- * wall clock and leaves the server able to speak.
530
- */
531
- addFavorite(input: AddFavoriteInput): Promise<AddFavoriteResult>;
532
- /**
533
- * Remove a favourite and the place record it owns.
534
- *
535
- * `Z_MAX` is deliberately NOT rolled back. Core Data never reuses a primary
536
- * key, and decrementing the counter would hand the next insert one that is
537
- * already spoken for by a row still referenced elsewhere.
538
- */
539
- removeFavorite(key: EntityKey): boolean;
540
- }
541
- //#endregion
542
559
  //#region src/client/maps.d.ts
543
560
  /**
544
561
  * The client.
@@ -598,29 +615,31 @@ type CreateClientOptions = {
598
615
  /** Injected by tests so discovery never reaches the developer's real home. */
599
616
  home?: string;
600
617
  /**
601
- * The interface lane, for tests.
602
- *
603
- * A seam of the same shape as `home`: null pins the store-only surface on a
604
- * machine that IS hosted, and a stub drives the interface lane on one that is
605
- * not. Undefined means "ask the environment", which is what the server does.
618
+ * The store lane, for tests. A seam of the same shape as `home`: null pins
619
+ * the npm surface on a machine that IS hosted, a lane opened on a stub socket
620
+ * drives the lane tools, and undefined asks the environment, which is what
621
+ * the server does.
606
622
  */
607
- ax?: MapsAxLane | null | undefined;
623
+ lane?: MapsLane | null | undefined;
624
+ /**
625
+ * How a place is opened in Maps to seed a record, for tests, so a suite never
626
+ * launches the app. Undefined is `open -g`.
627
+ */
628
+ openUrl?: OpenUrl | undefined;
608
629
  };
609
630
  declare class AppleMapsClient {
610
631
  #private;
611
632
  constructor(opts: CreateClientOptions);
612
633
  get config(): Config;
613
- get axLane(): MapsAxLane | null;
634
+ get lane(): MapsLane | null;
614
635
  located(): LocateResult;
615
636
  /**
616
- * A writer bound to the located store, or an error explaining why not.
617
- *
618
- * Writes go through their own read-write connection rather than the shared
619
- * read-only one: `store()` opens with `query_only` and an `immutable` fallback
620
- * precisely so a read can never mutate by accident, and widening it would
621
- * throw that guarantee away for every read on the surface.
637
+ * A read-only finder of place records for the store lane, bound to the
638
+ * located store, or an error explaining why not. It writes nothing: the lane
639
+ * does the writing, through Maps' own model. Its own connections, rather than
640
+ * the shared one `store()` opens, because it must not hold one across a seed.
622
641
  */
623
- writer(openUrl?: OpenUrl): MapsWriter;
642
+ placeSource(openUrl?: OpenUrl | undefined): PlaceSourceFinder;
624
643
  /** Open the store, once, lazily. Every read goes through here. */
625
644
  store(): MapsStore;
626
645
  get epoch(): Epoch;
@@ -716,15 +735,21 @@ declare const createServer: (opts: CreateServerOptions) => CreatedServer;
716
735
  //#region src/tools/index.d.ts
717
736
  type ToolContext = {
718
737
  /**
719
- * Gates the two mutating tools, which are NOT registered when it is false —
720
- * so a host that has not opted in is never told they exist.
738
+ * Gates the mutating tools, which are NOT registered when it is false, so a
739
+ * host that has not opted in is never told they exist.
721
740
  *
722
- * This surface writes SQL directly into Maps' Core Data store, because Maps
723
- * has no scripting dictionary and no App Intents to write through. The store
724
- * is mirrored to iCloud, so a write here reaches every device on the account.
725
- * `docs/maps.md` carries the measurements; `client/write.ts` carries the rule
726
- * that makes it safe — never fabricate a place record, only copy one Maps
727
- * wrote itself.
741
+ * It is necessary and not sufficient. Maps has no scripting dictionary and
742
+ * no App Intents to write through, so its one write route is Cupertino's
743
+ * store lane, which saves with Maps' own Core Data model; on 2026-11-11 every
744
+ * one of its five writes was seen on a Mac and an iPhone, one with Maps quit.
745
+ * Run from npm there is no lane, and this server registers no write tool
746
+ * whatever this says. The SQL and Accessibility routes it once had were
747
+ * retired the same day: the watch found the SQL inserts never mirrored to
748
+ * iCloud, and saw Maps convert favourites that look like them (no mirror
749
+ * row, no `shortcutIdentifier`, a small `positionIndex`) into saved places.
750
+ * `docs/maps.md` carries
751
+ * the measurements. The rule that outlived them: never fabricate a place
752
+ * record, only copy one Maps wrote itself.
728
753
  */
729
754
  allowWrites: boolean;
730
755
  };
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/client/dates.ts","../src/client/errors.ts","../src/client/locate.ts","../src/config.ts","../src/client/ax.ts","../src/client/store.ts","../src/client/ref.ts","../src/client/write.ts","../src/client/maps.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/client/dates.ts","../src/client/errors.ts","../src/client/locate.ts","../src/config.ts","../src/client/open-url.ts","../src/client/store.ts","../src/client/place-source.ts","../src/client/lane.ts","../src/client/ref.ts","../src/client/maps.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
- import { A as fromStoreTime, C as MAPS_SURFACE, D as UndatableStoreError, E as SchemaDriftError, M as resolveEpoch, N as BUILD_INFO, O as APPLE_SECONDS, S as MAPS_BUNDLE_ID, T as PlaceNotFoundError, _ as defaultDirectory, a as loadConfig, b as AppleMapsError, c as introspect, d as InvalidMapsRefError, f as PLACE_REF_VERSION, g as encodePlaceRef, h as encodeCollectionRef, i as registerTools, j as renderInstant, k as CORE_DATA_EPOCH_OFFSET, l as openStore, m as decodePlaceRef, n as SERVER_VERSION, o as AppleMapsClient, p as decodeCollectionRef, r as createServer, s as MapsStore, t as SERVER_NAME, u as COLLECTION_REF_VERSION, v as defaultStorePath, w as MapsStoreUnavailableError, x as IndexUnavailableError, y as locateStore } from "./server-C5JyIvr1.js";
1
+ import { A as fromStoreTime, C as MAPS_SURFACE, D as UndatableStoreError, E as SchemaDriftError, M as resolveEpoch, N as BUILD_INFO, O as APPLE_SECONDS, S as MAPS_BUNDLE_ID, T as PlaceNotFoundError, _ as defaultDirectory, a as loadConfig, b as AppleMapsError, c as introspect, d as InvalidMapsRefError, f as PLACE_REF_VERSION, g as encodePlaceRef, h as encodeCollectionRef, i as registerTools, j as renderInstant, k as CORE_DATA_EPOCH_OFFSET, l as openStore, m as decodePlaceRef, n as SERVER_VERSION, o as AppleMapsClient, p as decodeCollectionRef, r as createServer, s as MapsStore, t as SERVER_NAME, u as COLLECTION_REF_VERSION, v as defaultStorePath, w as MapsStoreUnavailableError, x as IndexUnavailableError, y as locateStore } from "./server-QidAKfSq.js";
2
2
  export { APPLE_SECONDS, AppleMapsClient, AppleMapsError, BUILD_INFO, COLLECTION_REF_VERSION, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, InvalidMapsRefError, MAPS_BUNDLE_ID, MAPS_SURFACE, MapsStore, MapsStoreUnavailableError, PLACE_REF_VERSION, PlaceNotFoundError, SERVER_NAME, SERVER_VERSION, SchemaDriftError, UndatableStoreError, createServer, decodeCollectionRef, decodePlaceRef, defaultDirectory, defaultStorePath, encodeCollectionRef, encodePlaceRef, fromStoreTime, introspect, loadConfig, locateStore, openStore, registerTools, renderInstant, resolveEpoch };