bkmrk 0.1.0__tar.gz

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.
bkmrk-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Jeremy Tabke
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
bkmrk-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,420 @@
1
+ Metadata-Version: 2.4
2
+ Name: bkmrk
3
+ Version: 0.1.0
4
+ Summary: Plain-text, pass-style bookmarks
5
+ License: MIT License
6
+
7
+ Copyright (c) 2025 Jeremy Tabke
8
+
9
+ Permission is hereby granted, free of charge, to any person obtaining a copy
10
+ of this software and associated documentation files (the "Software"), to deal
11
+ in the Software without restriction, including without limitation the rights
12
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13
+ copies of the Software, and to permit persons to whom the Software is
14
+ furnished to do so, subject to the following conditions:
15
+
16
+ The above copyright notice and this permission notice shall be included in all
17
+ copies or substantial portions of the Software.
18
+
19
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25
+ SOFTWARE.
26
+
27
+ Classifier: Programming Language :: Python :: 3
28
+ Classifier: License :: OSI Approved :: MIT License
29
+ Classifier: Operating System :: OS Independent
30
+ Requires-Python: >=3.8
31
+ Description-Content-Type: text/markdown
32
+ License-File: LICENSE
33
+ Provides-Extra: dev
34
+ Requires-Dist: pytest>=7.0; extra == "dev"
35
+ Requires-Dist: pytest-cov; extra == "dev"
36
+ Requires-Dist: ruff; extra == "dev"
37
+ Requires-Dist: pre-commit; extra == "dev"
38
+ Requires-Dist: commitizen; extra == "dev"
39
+ Provides-Extra: build
40
+ Requires-Dist: twine; extra == "build"
41
+ Requires-Dist: build; extra == "build"
42
+ Dynamic: license-file
43
+
44
+ # bm — plain‑text bookmarks
45
+
46
+ A tiny, **stdlib‑only** bookmark manager inspired by the Unix philosophy and `pass`:
47
+
48
+ - **One text file per bookmark** (`.bm`) with front matter + freeform notes
49
+ - **Human‑readable paths** with a short hash to avoid collisions
50
+ - **Stable IDs** derived from the URL (rename‑safe)
51
+ - **Greppable** store; composable CLI
52
+ - **Atomic writes** & path‑safety checks
53
+ - **JSON / JSONL** output for pipelines
54
+ - **Netscape HTML import/export** for browser interoperability
55
+ - **Optional Git sync** for history and cross‑device
56
+
57
+ > Works on macOS, Linux, WSL, and Windows (PowerShell). No third‑party dependencies.
58
+
59
+ ---
60
+
61
+ ## Table of contents
62
+
63
+ - [Why bm?](#why-bm)
64
+ - [Install](#install)
65
+ - [Quickstart](#quickstart)
66
+ - [Concepts](#concepts)
67
+ - [Store layout](#store-layout)
68
+ - [Bookmark file format](#bookmark-file-format)
69
+ - [IDs](#ids)
70
+
71
+ - [CLI usage](#cli-usage)
72
+ - [`init`](#init)
73
+ - [`add`](#add)
74
+ - [`list`](#list)
75
+ - [`search`](#search)
76
+ - [`show` and `open`](#show-and-open)
77
+ - [`edit`, `rm`, `mv`](#edit-rm-mv)
78
+ - [`tags` and `tag add|rm`](#tags-and-tag-addrm)
79
+ - [`dirs`](#dirs)
80
+ - [`export` and `import`](#export-and-import)
81
+ - [`sync`](#sync)
82
+
83
+ - [Filtering & output formats](#filtering--output-formats)
84
+ - [Integration recipes](#integration-recipes)
85
+ - [Configuration](#configuration)
86
+ - [Security & robustness](#security--robustness)
87
+ - [Migration notes](#migration-notes)
88
+ - [Development](#development)
89
+ - [License](#license)
90
+
91
+ ---
92
+
93
+ ## Why bm?
94
+
95
+ Most bookmark tools are databases or browser‑locked. `bm` chooses **text first**: plain UTF‑8 files that last decades, are easy to diff, and play well with your editor, shell, and Git. It embraces "do one thing well" and stays small so you can integrate it anywhere.
96
+
97
+ ---
98
+
99
+ ## Install
100
+
101
+ Requires Python >=3.8. Install with `pip` (or `pipx`) to get the `bm` console script:
102
+
103
+ ```bash
104
+ git clone https://github.com/jtabke/bkmrk
105
+ cd bkmrk
106
+ python -m pip install .
107
+ ```
108
+
109
+ Development workflows can pull in the optional extras declared in `pyproject.toml`:
110
+
111
+ ```bash
112
+ python -m pip install -e '.[dev]'
113
+ ```
114
+
115
+ Prefer running straight from the repository? The module entry point works without
116
+ installation:
117
+
118
+ ```bash
119
+ python -m bm --help
120
+ ```
121
+
122
+ On Windows (PowerShell):
123
+
124
+ ```powershell
125
+ python -m bm --help
126
+ ```
127
+
128
+ ---
129
+
130
+ ## Quickstart
131
+
132
+ ```bash
133
+ # initialize a new store (optionally a git repo)
134
+ bm init --git
135
+
136
+ # import bookmarks from a browser export (Netscape HTML)
137
+ bm import netscape ~/Downloads/bookmarks.html
138
+
139
+ # add a bookmark
140
+ bm add https://example.com -n "Example" -t ref,demo -d "Short note"
141
+
142
+ # list newest bookmarks (ID, path, title, URL)
143
+ bm list
144
+
145
+ # search across title/url/tags/body
146
+ bm search kernel
147
+
148
+ # search within a specific path
149
+ bm search kernel --path dev/linux
150
+
151
+ # list directory prefixes
152
+ bm dirs
153
+
154
+ # open the first result
155
+ ID=$(bm search kernel --jsonl | head -1 | jq -r '.id')
156
+ bm open "$ID"
157
+
158
+ # export for browsers (Netscape HTML)
159
+ bm export netscape > bookmarks.html
160
+ ```
161
+
162
+ ---
163
+
164
+ ## Concepts
165
+
166
+ ### Store layout
167
+
168
+ Default store directory is `~/.bookmarks.d` (override via `$BOOKMARKS_DIR`). Each bookmark is a single `.bm` file; directories serve as namespaces.
169
+
170
+ ```
171
+ ~/.bookmarks.d/
172
+ dev/python/fastapi-3a1b2c4.bm
173
+ news-ycombinator-com-1234567.bm
174
+ README.txt
175
+ ```
176
+
177
+ File names are **human readable** and end with a **short hash of the URL** to avoid collisions.
178
+
179
+ ### Bookmark file format
180
+
181
+ Each `.bm` file contains front matter and an optional body:
182
+
183
+ ```text
184
+ ---
185
+ url: https://example.com/blog/post
186
+ title: Great post
187
+ tags: [read, blog, "needs,comma"]
188
+ created: 2025-09-16T08:42:00-07:00
189
+ modified: 2025-09-17T09:10:00-07:00
190
+ ---
191
+ Longer notes, checklists, code blocks…
192
+ ```
193
+
194
+ - `tags` is a list and supports quoting for commas/spaces
195
+ - Any extra keys are preserved on round‑trip
196
+
197
+ ### IDs
198
+
199
+ Each bookmark has a **stable ID** derived from its URL (BLAKE2b short hash). The ID does **not** change if you rename/move the file. You can use either the ID **or** a path‑like slug with commands.
200
+
201
+ ---
202
+
203
+ ## CLI usage
204
+
205
+ Run `bm --help` or `bm <command> --help` for command details.
206
+
207
+ ### `init`
208
+
209
+ Create a store; optional `--git` initializes a Git repo.
210
+
211
+ ```bash
212
+ bm init --git
213
+ ```
214
+
215
+ ### `add`
216
+
217
+ Add a bookmark. `--edit` opens your `$EDITOR` with a pre‑filled template.
218
+
219
+ ```bash
220
+ bm add <url> [-n TITLE] [-t tag1,tag2] [-d NOTES] [-p dir1/dir2] [--id SLUG] [--edit] [-f]
221
+ ```
222
+
223
+ Prints the stable ID on success.
224
+
225
+ ### `list`
226
+
227
+ List bookmarks (newest first).
228
+
229
+ ```bash
230
+ bm list [--host HOST] [--since ISO|YYYY-MM-DD] [-t TAG] [--path PREFIX] [--json|--jsonl]
231
+ ```
232
+
233
+ ### `search`
234
+
235
+ Full‑text search across title, url, tags, and body.
236
+
237
+ ```bash
238
+ bm search <query> [--path PREFIX] [--json|--jsonl]
239
+ ```
240
+
241
+ ### `show` and `open`
242
+
243
+ Display metadata/notes or open the URL in your default browser:
244
+
245
+ ```bash
246
+ bm show <ID|path>
247
+ bm open <ID|path>
248
+ ```
249
+
250
+ ### `edit`, `rm`, `mv`
251
+
252
+ ```bash
253
+ bm edit <ID|path> # bumps modified timestamp
254
+ bm rm <ID|path>
255
+ bm mv <SRC> <DST> [-f]
256
+ ```
257
+
258
+ ### `tags` and `tag add|rm`
259
+
260
+ List discovered tags (from folder segments and header tags), or mutate tags without opening an editor.
261
+
262
+ ```bash
263
+ bm tags
264
+ bm tag add <ID|path> tag1 tag2
265
+ bm tag rm <ID|path> tag1
266
+ ```
267
+
268
+ ### `dirs`
269
+
270
+ List all known directory prefixes in the bookmark store.
271
+
272
+ ```bash
273
+ bm dirs [--json]
274
+ ```
275
+
276
+ ### `export` and `import`
277
+
278
+ Netscape HTML (for browsers) and JSON exports; Netscape import with folder hierarchies preserved.
279
+
280
+ ```bash
281
+ bm export netscape [--host HOST] [--since ISO|YYYY-MM-DD] > bookmarks.html
282
+ bm export json > dump.json
283
+ bm import netscape bookmarks.html [-f]
284
+ ```
285
+
286
+ ### `sync`
287
+
288
+ If the store is a Git repo, stage/commit and (if upstream exists) push.
289
+
290
+ ```bash
291
+ bm sync
292
+ ```
293
+
294
+ ---
295
+
296
+ ## Filtering & output formats
297
+
298
+ - `--host` matches the URL host (case‑insensitive, ignores leading `www.`)
299
+ - `--path` filters by path prefix (e.g., `--path dev/python` shows only entries under that directory tree)
300
+ - `--since` accepts `YYYY-MM-DD` or full ISO timestamps; comparisons are proper datetimes
301
+ - `--json` emits a single JSON array; `--jsonl` outputs one JSON object per line (NDJSON)
302
+
303
+ Common JSON schema fields: `id`, `path`, `title`, `url`, `tags`, `created`, `modified`.
304
+
305
+ ---
306
+
307
+ ## Integration recipes
308
+
309
+ **fzf launcher**
310
+
311
+ ```bash
312
+ bm list --jsonl | fzf --with-nth=2.. | awk '{print $1}' | xargs -r bm open
313
+ ```
314
+
315
+ **Open the latest saved from a host**
316
+
317
+ ```bash
318
+ bm list --host example.com --jsonl | head -1 | jq -r '.id' | xargs -r bm open
319
+ ```
320
+
321
+ **Bulk tag HN links**
322
+
323
+ ```bash
324
+ bm list --host news.ycombinator.com --jsonl | jq -r '.id' | xargs -n1 bm tag add hn
325
+ ```
326
+
327
+ **List bookmarks in a specific category**
328
+
329
+ ```bash
330
+ bm list --path dev/python
331
+ bm search "framework" --path dev
332
+ ```
333
+
334
+ **Explore directory structure**
335
+
336
+ ```bash
337
+ bm dirs
338
+ bm dirs --json | jq
339
+ ```
340
+
341
+ **Export → browser import**
342
+
343
+ ```bash
344
+ bm export netscape > ~/Desktop/bookmarks.html
345
+ # Import that file in your browser’s bookmarks manager
346
+ ```
347
+
348
+ **Sync with Syncthing**
349
+
350
+ For cross-device synchronization without Git, use [Syncthing](https://syncthing.net/) to sync your bookmark store:
351
+
352
+ 1. Install Syncthing on all devices.
353
+ 2. Add your bookmark store directory (`~/.bookmarks.d` or `$BOOKMARKS_DIR`) as a synced folder in Syncthing.
354
+ 3. Configure devices to share the folder bidirectionally.
355
+ 4. Syncthing will keep your bookmarks in sync across devices automatically.
356
+
357
+ **Auto-export for browser import**
358
+
359
+ To automatically export bookmarks to Netscape HTML for browser import:
360
+
361
+ ```bash
362
+ #!/bin/bash
363
+ # auto_export.sh
364
+ bm export netscape > ~/bookmarks_auto.html
365
+ echo "Bookmarks exported to ~/bookmarks_auto.html. Import this file in your browser."
366
+ ```
367
+
368
+ Run this script periodically or on demand to generate an up-to-date bookmark file for browser import.
369
+
370
+ ---
371
+
372
+ ## Configuration
373
+
374
+ - **Store directory**: set `BOOKMARKS_DIR` or pass `--store` to any command
375
+ - **Editor**: `VISUAL` or `EDITOR` (supports commands like `code --wait`)
376
+
377
+ Windows notes:
378
+
379
+ - Paths avoid reserved names and use atomic replaces; long paths depend on OS settings
380
+
381
+ ---
382
+
383
+ ## Security & robustness
384
+
385
+ - **Atomic writes**: all modifications write to a temp file then `os.replace` it
386
+ - **Path safety**: `..` and absolute paths are rejected; files cannot escape the store
387
+ - **No network by default**: `bm` never fetches content (future hooks can)
388
+ - **Git**: pushes only if an upstream is configured
389
+
390
+ ---
391
+
392
+ ## Migration notes
393
+
394
+ From older versions where IDs depended on path: IDs are now **URL‑only** (stable across renames). Old files remain valid; tags as comma strings are still read and normalized to lists on save.
395
+
396
+ ---
397
+
398
+ ## Development
399
+
400
+ ```bash
401
+ # lint (optional) — stdlib only, so just run the script
402
+ python3 -m py_compile bm.py
403
+
404
+ # run tests (if added)
405
+ pytest -q
406
+ ```
407
+
408
+ ### Roadmap / ideas
409
+
410
+ - `bm dedupe` (merge by normalized URL, union tags)
411
+ - `bm reindex` + optional on‑disk index for very large stores
412
+ - Markdown/CSV exports
413
+ - Simple HTTP UI (`bm serve`) and browser extension hooks
414
+ - Optional encryption (GPG or git‑crypt) for private notes
415
+
416
+ ---
417
+
418
+ ## [ License ](./LICENSE)
419
+
420
+ MIT. Do what you want; a credit is appreciated.