apple-journal-cli 1.0.6 → 1.2.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 +55 -11
- package/bin/journal-cli +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -96,13 +96,20 @@ journal-cli write --live --body "Golden hour" --live-photo IMG_0123.heic IMG_012
|
|
|
96
96
|
|
|
97
97
|
# location pin
|
|
98
98
|
journal-cli write --live --body "At the office" \
|
|
99
|
-
--lat 47.62055 --lon -122.34930 --place "Space Needle" --city Seattle
|
|
99
|
+
--lat 47.62055 --lon -122.34930 --place "Space Needle" --city Seattle \
|
|
100
|
+
--location-presentation off # off, small (default), or large
|
|
100
101
|
|
|
101
102
|
# web link (renders as a rich link card)
|
|
102
103
|
journal-cli write --live --body "Read this" --link https://example.com --link-title "A Post"
|
|
103
104
|
|
|
104
|
-
#
|
|
105
|
+
# markdown -> Journal's own rich text (bold, italic, lists, strikethrough)
|
|
106
|
+
journal-cli write --live --markdown --body-file entry.md
|
|
107
|
+
|
|
108
|
+
# stage in a Mac-local journal; link photos back to the Photos library
|
|
105
109
|
journal-cli write --live --journal "Travel" --body "..." --media IMG_0079.JPG --photos-link
|
|
110
|
+
|
|
111
|
+
# audit staged memberships and print the native Journal.app finalization steps
|
|
112
|
+
journal-cli sync-journals --journal "Travel"
|
|
106
113
|
```
|
|
107
114
|
|
|
108
115
|
### Editing
|
|
@@ -113,7 +120,7 @@ journal-cli edit 103 --live --lat 47.6 --lon -122.3 --place Home # set/replace
|
|
|
113
120
|
journal-cli edit 103 --live --add-media c.heic --add-link https://example.org
|
|
114
121
|
journal-cli edit 103 --live --remove-media 700 # ids shown by `show`
|
|
115
122
|
journal-cli edit 103 --live --clear-location --no-bookmark
|
|
116
|
-
journal-cli edit 103 --live --journal "Travel" #
|
|
123
|
+
journal-cli edit 103 --live --journal "Travel" # stage an imported entry
|
|
117
124
|
```
|
|
118
125
|
|
|
119
126
|
### Deleting
|
|
@@ -125,6 +132,43 @@ journal-cli empty --live # purge never-synced deleted entries
|
|
|
125
132
|
journal-cli delete 103 --live --hard # full row+file removal (guarded, see below)
|
|
126
133
|
```
|
|
127
134
|
|
|
135
|
+
## Coming from Day One?
|
|
136
|
+
|
|
137
|
+
`skills/dayone-import/` migrates Day One journals into Apple Journal, entry
|
|
138
|
+
by entry, with photos, locations, titles and bookmarks intact.
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
S=skills/dayone-import/scripts/dayone-import.py
|
|
142
|
+
|
|
143
|
+
python3 $S journals # list Day One journals
|
|
144
|
+
python3 $S plan "Travel Journal" # what imports, and what can't
|
|
145
|
+
python3 $S import "Travel Journal" --into "Travel" --location-presentation off --target-db "$(journal-cli sandbox --dir /tmp/r)"
|
|
146
|
+
python3 $S import "Travel Journal" --into "Travel"
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
It reads Day One's own SQLite store rather than its markdown export, because
|
|
150
|
+
the export **renders every timestamp in the exporting machine's timezone**.
|
|
151
|
+
Entries written abroad come out hours off and some land on the wrong day. The
|
|
152
|
+
original zone is in the store, so the import can preserve the wall clock you
|
|
153
|
+
actually experienced. `fix-export` repairs an export you already have.
|
|
154
|
+
|
|
155
|
+
Two more things it knows:
|
|
156
|
+
|
|
157
|
+
- **Day One's location is where the *app* was**, not where the photos were
|
|
158
|
+
taken — entries written up later carry your home address. `fix-locations`
|
|
159
|
+
corrects them from photo EXIF, corroborated against the Photos library so a
|
|
160
|
+
camera with a stale GPS fix can't drag a whole trip to one spot.
|
|
161
|
+
- **Day One keeps media cloud-only** until asked. A journal can look complete
|
|
162
|
+
in the app while almost nothing is on disk. `plan` reports the shortfall
|
|
163
|
+
before you import anything.
|
|
164
|
+
- **Day One writes Markdown, Journal renders rich text.** Entries are
|
|
165
|
+
converted with `--markdown`, so headings become bold, `- ` and `1. ` become
|
|
166
|
+
real lists, and Day One's `\.` escaping disappears instead of showing up
|
|
167
|
+
literally. `fix-text` re-renders entries imported before this existed.
|
|
168
|
+
|
|
169
|
+
Imports are resumable, keyed by Day One's entry UUIDs, so re-running never
|
|
170
|
+
double-writes.
|
|
171
|
+
|
|
128
172
|
## Agent-friendly by design
|
|
129
173
|
|
|
130
174
|
journal-cli is built to be driven by AI agents and scripts as much as by
|
|
@@ -143,9 +187,9 @@ humans:
|
|
|
143
187
|
hands back a disposable copy of the store; every other command accepts
|
|
144
188
|
`--db` (or `$JOURNAL_DB`) to target it. Agents can rehearse a write with
|
|
145
189
|
zero risk, then replay it `--live`.
|
|
146
|
-
- **
|
|
190
|
+
- **Skills ship in-repo** — `skills/journal-cli/SKILL.md` teaches
|
|
147
191
|
Claude-style agents the command surface, the safety model, and the sharp
|
|
148
|
-
edges.
|
|
192
|
+
edges; `skills/dayone-import/SKILL.md` covers migrating from Day One.
|
|
149
193
|
|
|
150
194
|
## Safety model
|
|
151
195
|
|
|
@@ -170,14 +214,14 @@ engine uploads them all to CloudKit — including the attachment files — and a
|
|
|
170
214
|
delete/restore round trip propagates. The read pipeline has been swept over an
|
|
171
215
|
entire real store: every entry row and all ~700 asset metadata blobs parse.
|
|
172
216
|
|
|
173
|
-
The test suite (`tests/test_write.sh
|
|
217
|
+
The test suite (`tests/test_write.sh`) runs the whole command
|
|
174
218
|
surface against a disposable copy of a store — argument guards, insert
|
|
175
219
|
bookkeeping, RTF round-trips, location metadata, media file layout, Live Photo
|
|
176
220
|
pairing, Photos linkage, journal targeting, link assets, the delete/restore
|
|
177
221
|
lifecycle, and `PRAGMA integrity_check`. Point `JOURNAL_SEED` at a backup to
|
|
178
222
|
run it without Full Disk Access. `JOURNAL_CLI` selects the binary under test;
|
|
179
|
-
the Python
|
|
180
|
-
|
|
223
|
+
the Python implementation in `reference/` remains an executable reference for
|
|
224
|
+
the original command surface.
|
|
181
225
|
|
|
182
226
|
## How it works
|
|
183
227
|
|
|
@@ -200,7 +244,7 @@ the sync cache.)
|
|
|
200
244
|
| asset metadata | one version byte `0x01` + JSON; `0x02` + UUID = Core Data external storage in `.moments_SUPPORT/_EXTERNAL_DATA/` |
|
|
201
245
|
| links | base64 `NSKeyedArchiver`-archived `LPLinkMetadata` inside the asset metadata |
|
|
202
246
|
| audio | asset metadata carries duration, waveform, and a word-level transcript |
|
|
203
|
-
| journals | `ZJOURNALMO` (names live in each journal's
|
|
247
|
+
| journals | `ZJOURNALMO` (names live in each journal's merge blob) + `Z_5JOURNALS` join; direct join changes are Mac-local until Journal.app performs a native move and authors the per-entry merge data |
|
|
204
248
|
| new-row bookkeeping | fresh `Z_PK`, bumped `Z_PRIMARYKEY.Z_MAX`, 16-byte UUID `ZID`, `ZISUPLOADEDTOCLOUD=0` — Journal's sync engine adopts the row and uploads it |
|
|
205
249
|
|
|
206
250
|
### The CRDT limitation
|
|
@@ -218,8 +262,8 @@ entry whose text was typed in the app. Consequences:
|
|
|
218
262
|
- **`edit` refuses to rewrite text on CRDT-bearing entries** unless `--force`
|
|
219
263
|
is passed: rewriting only the RTF leaves the CRDT holding the old text with
|
|
220
264
|
authoritative history, and sync can revert or duplicate the edit. Location,
|
|
221
|
-
media, links, date, bookmark
|
|
222
|
-
|
|
265
|
+
media, links, date, and bookmark remain editable. Journal moves on entries
|
|
266
|
+
with merge data must be performed in Journal.app so they sync correctly.
|
|
223
267
|
- **CLI-written entries have no CRDT.** Journal renders and syncs them fine,
|
|
224
268
|
but a simultaneous edit on two devices may not merge like an app-authored
|
|
225
269
|
entry would.
|
package/bin/journal-cli
CHANGED
|
Binary file
|