@mgcrea/mcp-apple-maps 1.38.0 → 1.42.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 +43 -36
- package/dist/cli.js +1 -1
- package/dist/index.d.ts +222 -197
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/{server-m9kFpx0N.js → server--c2qkmbX.js} +795 -902
- package/dist/server--c2qkmbX.js.map +1 -0
- package/package.json +3 -3
- package/dist/server-m9kFpx0N.js.map +0 -1
package/README.md
CHANGED
|
@@ -28,25 +28,33 @@ from Maps' Core Data store.
|
|
|
28
28
|
|
|
29
29
|
## What it writes
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
|
|
49
|
-
|
|
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
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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
|
|
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
|
|
2
|
+
import { C as MAPS_SURFACE, N as BUILD_INFO, a as loadConfig, r as createServer } from "./server--c2qkmbX.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,
|
|
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
|
|
98
|
-
* Maps has no scripting dictionary and no registered App
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
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/
|
|
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
|
|
127
|
+
* How a place is opened in Maps, so Maps mints the place record a write copies.
|
|
133
128
|
*
|
|
134
|
-
*
|
|
135
|
-
*
|
|
136
|
-
*
|
|
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
|
|
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
|
|
602
|
-
*
|
|
603
|
-
*
|
|
604
|
-
*
|
|
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
|
-
|
|
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
|
|
634
|
+
get lane(): MapsLane | null;
|
|
614
635
|
located(): LocateResult;
|
|
615
636
|
/**
|
|
616
|
-
* A
|
|
617
|
-
*
|
|
618
|
-
*
|
|
619
|
-
*
|
|
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
|
-
|
|
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
|
|
720
|
-
*
|
|
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
|
-
*
|
|
723
|
-
*
|
|
724
|
-
*
|
|
725
|
-
*
|
|
726
|
-
*
|
|
727
|
-
*
|
|
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
|
};
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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/
|
|
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
|
|
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--c2qkmbX.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 };
|