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