apple-journal-cli 1.2.0 → 1.4.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 +54 -4
- package/bin/journal-cli +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -51,6 +51,8 @@ Security), then:
|
|
|
51
51
|
journal-cli doctor
|
|
52
52
|
```
|
|
53
53
|
|
|
54
|
+
Release history and upgrade notes: [CHANGELOG.md](CHANGELOG.md).
|
|
55
|
+
|
|
54
56
|
## Reading
|
|
55
57
|
|
|
56
58
|
Reads run against a temp snapshot of the store, so they are safe while
|
|
@@ -61,6 +63,9 @@ journal-cli list --limit 20 --full # --full prints bodies
|
|
|
61
63
|
journal-cli list --since 2025-01-01 --until 2025-12-31
|
|
62
64
|
journal-cli show 95 # entry + assets + attachment paths
|
|
63
65
|
journal-cli search tokyo
|
|
66
|
+
journal-cli write --body "Ran a 5K" --journal Fitness --add-journal Mindset --live
|
|
67
|
+
journal-cli edit 42 --add-journal Leisure --live # keeps existing memberships
|
|
68
|
+
journal-cli edit 42 --remove-journal Leisure --live
|
|
64
69
|
journal-cli export --dir ~/journal-export # one .md per entry, YAML frontmatter
|
|
65
70
|
journal-cli export --dir ~/export --format json
|
|
66
71
|
journal-cli stats # counts, words, by-year histogram
|
|
@@ -97,7 +102,7 @@ journal-cli write --live --body "Golden hour" --live-photo IMG_0123.heic IMG_012
|
|
|
97
102
|
# location pin
|
|
98
103
|
journal-cli write --live --body "At the office" \
|
|
99
104
|
--lat 47.62055 --lon -122.34930 --place "Space Needle" --city Seattle \
|
|
100
|
-
--location-presentation
|
|
105
|
+
--location-presentation large # small (default) or large
|
|
101
106
|
|
|
102
107
|
# web link (renders as a rich link card)
|
|
103
108
|
journal-cli write --live --body "Read this" --link https://example.com --link-title "A Post"
|
|
@@ -123,6 +128,16 @@ journal-cli edit 103 --live --clear-location --no-bookmark
|
|
|
123
128
|
journal-cli edit 103 --live --journal "Travel" # stage an imported entry
|
|
124
129
|
```
|
|
125
130
|
|
|
131
|
+
### Repairing
|
|
132
|
+
|
|
133
|
+
```sh
|
|
134
|
+
journal-cli repair-locations --dry-run # find maps written by 1.2.0's `off`
|
|
135
|
+
journal-cli repair-locations --live # restore them as small map cards
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Only needed if you used `--location-presentation off` on journal-cli 1.2.0.
|
|
139
|
+
See "Why there is no location `off`" below.
|
|
140
|
+
|
|
126
141
|
### Deleting
|
|
127
142
|
|
|
128
143
|
```sh
|
|
@@ -142,7 +157,7 @@ S=skills/dayone-import/scripts/dayone-import.py
|
|
|
142
157
|
|
|
143
158
|
python3 $S journals # list Day One journals
|
|
144
159
|
python3 $S plan "Travel Journal" # what imports, and what can't
|
|
145
|
-
python3 $S import "Travel Journal" --into "Travel" --location-presentation
|
|
160
|
+
python3 $S import "Travel Journal" --into "Travel" --location-presentation large --target-db "$(journal-cli sandbox --dir /tmp/r)"
|
|
146
161
|
python3 $S import "Travel Journal" --into "Travel"
|
|
147
162
|
```
|
|
148
163
|
|
|
@@ -211,7 +226,9 @@ Every write path has been verified against a real library on macOS 26:
|
|
|
211
226
|
Journal.app renders CLI-written text, photos, Live Photos (labeled as such),
|
|
212
227
|
link cards, and location pins (which also feed its Places index); the sync
|
|
213
228
|
engine uploads them all to CloudKit — including the attachment files — and a
|
|
214
|
-
delete/restore round trip propagates.
|
|
229
|
+
delete/restore round trip propagates. Map cards were checked against the app's
|
|
230
|
+
three modes: `small` and `large` are reproducible from the asset row, `off` is
|
|
231
|
+
not (see "Why there is no location `off`"). The read pipeline has been swept over an
|
|
215
232
|
entire real store: every entry row and all ~700 asset metadata blobs parse.
|
|
216
233
|
|
|
217
234
|
The test suite (`tests/test_write.sh`) runs the whole command
|
|
@@ -219,7 +236,9 @@ surface against a disposable copy of a store — argument guards, insert
|
|
|
219
236
|
bookkeeping, RTF round-trips, location metadata, media file layout, Live Photo
|
|
220
237
|
pairing, Photos linkage, journal targeting, link assets, the delete/restore
|
|
221
238
|
lifecycle, and `PRAGMA integrity_check`. Point `JOURNAL_SEED` at a backup to
|
|
222
|
-
run it without Full Disk Access
|
|
239
|
+
run it without Full Disk Access, or point it at `tests/make-fixture.sh`'s
|
|
240
|
+
synthetic store to run with no Journal library at all (what CI does); the suite
|
|
241
|
+
is seed-independent and passes either way. `JOURNAL_CLI` selects the binary under test;
|
|
223
242
|
the Python implementation in `reference/` remains an executable reference for
|
|
224
243
|
the original command surface.
|
|
225
244
|
|
|
@@ -269,6 +288,37 @@ entry whose text was typed in the app. Consequences:
|
|
|
269
288
|
entry would.
|
|
270
289
|
- **Authoring the CRDT is out of scope** — fabricating causal history in a
|
|
271
290
|
reverse-engineered protobuf risks corrupting merge for that entry.
|
|
291
|
+
- **Some entry state lives only in the CRDT**, and so is not ours to write.
|
|
292
|
+
Location `off` is the known case — see below.
|
|
293
|
+
|
|
294
|
+
### Why there is no location `off`
|
|
295
|
+
|
|
296
|
+
Journal's map card has three modes (Off / Small / Large), but only two of them
|
|
297
|
+
are in the asset row. The size is `ZISSLIM`; **Off is recorded solely in the
|
|
298
|
+
entry's CRDT**, whose key table reads `title`, `gridAssetIDs`, `slimAssetID`,
|
|
299
|
+
`hiddenAssetIDs`, `assetPlacement`. An Off map is listed under
|
|
300
|
+
`hiddenAssetIDs` there, and its asset row stays byte-identical to a large
|
|
301
|
+
one — `ZISSLIM=0, ZISHIDDEN=0`.
|
|
302
|
+
|
|
303
|
+
Measured against a live store of 5,000+ assets: `ZISHIDDEN` is `0` on every
|
|
304
|
+
asset of every type, Journal never sets it, and on all 39 entries whose CRDT
|
|
305
|
+
carries `hiddenAssetIDs` the asset rows still read `ZISHIDDEN=0`. Five of
|
|
306
|
+
those entries have a map as their only asset and carry `hiddenAssetIDs` with
|
|
307
|
+
no `gridAssetIDs`/`slimAssetID`, which pins the meaning down exactly.
|
|
308
|
+
|
|
309
|
+
So `ZISHIDDEN=1` does not hide a map card. Journal treats the asset as absent
|
|
310
|
+
altogether: no card **and no Places entry**, the location effectively gone.
|
|
311
|
+
journal-cli 1.2.0 shipped `--location-presentation off` written that way;
|
|
312
|
+
1.3.0 refuses the flag rather than silently losing locations.
|
|
313
|
+
|
|
314
|
+
If you imported with 1.2.0, the coordinates are still in the rows and
|
|
315
|
+
`repair-locations` fixes them in place — no re-import:
|
|
316
|
+
|
|
317
|
+
```sh
|
|
318
|
+
journal-cli repair-locations --dry-run # count what is affected
|
|
319
|
+
journal-cli repair-locations --live # restore as small maps
|
|
320
|
+
journal-cli repair-locations --to large --live # or as large ones
|
|
321
|
+
```
|
|
272
322
|
|
|
273
323
|
### Not supported
|
|
274
324
|
|
package/bin/journal-cli
CHANGED
|
Binary file
|