zenform 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.
- zenform-0.1.0/.github/workflows/ci.yml +29 -0
- zenform-0.1.0/.github/workflows/publish.yml +38 -0
- zenform-0.1.0/.gitignore +12 -0
- zenform-0.1.0/AGENTS.md +38 -0
- zenform-0.1.0/LICENSE +21 -0
- zenform-0.1.0/PKG-INFO +123 -0
- zenform-0.1.0/README.md +104 -0
- zenform-0.1.0/docs/session-format.md +55 -0
- zenform-0.1.0/examples/config/essentials.toml +6 -0
- zenform-0.1.0/examples/config/folders/10-code.toml +7 -0
- zenform-0.1.0/examples/config/folders/20-tickets.toml +7 -0
- zenform-0.1.0/examples/config/zenform.toml +5 -0
- zenform-0.1.0/pyproject.toml +40 -0
- zenform-0.1.0/src/zenform/__init__.py +6 -0
- zenform-0.1.0/src/zenform/__main__.py +5 -0
- zenform-0.1.0/src/zenform/cli.py +201 -0
- zenform-0.1.0/src/zenform/config.py +161 -0
- zenform-0.1.0/src/zenform/favicons.py +86 -0
- zenform-0.1.0/src/zenform/model.py +409 -0
- zenform-0.1.0/src/zenform/mozlz4.py +86 -0
- zenform-0.1.0/src/zenform/profile.py +93 -0
- zenform-0.1.0/tests/helpers.py +54 -0
- zenform-0.1.0/tests/test_cli.py +117 -0
- zenform-0.1.0/tests/test_config.py +103 -0
- zenform-0.1.0/tests/test_favicons.py +93 -0
- zenform-0.1.0/tests/test_model.py +154 -0
- zenform-0.1.0/tests/test_mozlz4.py +44 -0
- zenform-0.1.0/tests/test_version.py +18 -0
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
name: ci
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ["3.11", "3.12", "3.13", "3.14"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
- uses: actions/setup-python@v5
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
- name: Tests (standard library only, warnings are errors)
|
|
20
|
+
run: PYTHONPATH=src python -W error -m unittest discover -s tests
|
|
21
|
+
- name: The example config is valid
|
|
22
|
+
run: PYTHONPATH=src python -c "from zenform import config, model; s = config.load_config('examples/config'); assert not model.validate_spec(s), model.validate_spec(s); assert not model.warnings(s), model.warnings(s)"
|
|
23
|
+
|
|
24
|
+
lint:
|
|
25
|
+
runs-on: ubuntu-latest
|
|
26
|
+
steps:
|
|
27
|
+
- uses: actions/checkout@v4
|
|
28
|
+
- uses: astral-sh/setup-uv@v5
|
|
29
|
+
- run: uvx ruff check .
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
name: publish
|
|
2
|
+
|
|
3
|
+
# Publishes to PyPI with Trusted Publishing (OIDC): no API token is stored anywhere.
|
|
4
|
+
# Runs when a GitHub release is published, so a release is the only way to publish.
|
|
5
|
+
on:
|
|
6
|
+
release:
|
|
7
|
+
types: [published]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
build:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
steps:
|
|
13
|
+
- uses: actions/checkout@v4
|
|
14
|
+
- uses: astral-sh/setup-uv@v5
|
|
15
|
+
- name: The tag matches the package version
|
|
16
|
+
run: |
|
|
17
|
+
v="$(python3 -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
|
|
18
|
+
test "v$v" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != pyproject version v$v"; exit 1; }
|
|
19
|
+
- run: PYTHONPATH=src python3 -W error -m unittest discover -s tests
|
|
20
|
+
- run: uv build
|
|
21
|
+
- run: uvx twine check dist/*
|
|
22
|
+
- uses: actions/upload-artifact@v4
|
|
23
|
+
with:
|
|
24
|
+
name: dist
|
|
25
|
+
path: dist/
|
|
26
|
+
|
|
27
|
+
publish:
|
|
28
|
+
needs: build
|
|
29
|
+
runs-on: ubuntu-latest
|
|
30
|
+
environment: pypi
|
|
31
|
+
permissions:
|
|
32
|
+
id-token: write
|
|
33
|
+
steps:
|
|
34
|
+
- uses: actions/download-artifact@v4
|
|
35
|
+
with:
|
|
36
|
+
name: dist
|
|
37
|
+
path: dist/
|
|
38
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
zenform-0.1.0/.gitignore
ADDED
zenform-0.1.0/AGENTS.md
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Two audiences: an agent **using** zenform to change someone's Zen sidebar, and an agent **developing** zenform.
|
|
4
|
+
|
|
5
|
+
## Using zenform (customising someone's pins)
|
|
6
|
+
|
|
7
|
+
You prepare a reviewed change to the config files. **Never run `zenform apply` (or `rollback`) on the live profile**:
|
|
8
|
+
Zen must be closed and the user decides when. Everything else is safe.
|
|
9
|
+
|
|
10
|
+
1. `zenform doctor`: profile found, Zen version tested, session readable, config valid.
|
|
11
|
+
2. `zenform dump --out <tmp>` if there is no config yet; otherwise read the existing config directory.
|
|
12
|
+
3. Edit the TOML files. Rules:
|
|
13
|
+
- `label`: 14 characters or fewer, specific, no emoji, no site name. Tickets: number first (`117 Exports`).
|
|
14
|
+
- `url`: the *landing page the user uses* (an MR list, a board), not whatever was open. To keep a pin's history
|
|
15
|
+
and icon, reuse the home URL exactly as `dump` printed it.
|
|
16
|
+
- One pin per line, in sidebar order. Folders are files; their order is the file-name order (`10-`, `20-`).
|
|
17
|
+
- No one-off pages (a single MR, a chat, a draft document), no duplicate URLs, at most 9 essentials (3x3 grid).
|
|
18
|
+
- Do not list a folder that is in `keep_folders`; do not touch it.
|
|
19
|
+
4. `zenform plan --json --no-favicons` and read `changes`: `add`, `relabel`, `move`, `unpin`, `remove_folder`.
|
|
20
|
+
`unpin` is not a close: the tab stays open as an ordinary tab. Show the user the plan as text (`zenform plan`).
|
|
21
|
+
5. Stop. Tell the user to quit Zen and run `zenform apply`; `zenform rollback` undoes it.
|
|
22
|
+
|
|
23
|
+
Unknown keys in the config are errors by design. If `plan` fails, read the message: it names the file and the key.
|
|
24
|
+
|
|
25
|
+
## Developing zenform
|
|
26
|
+
|
|
27
|
+
- **Standard library only.** No runtime dependencies (`dependencies = []`). It carries its own LZ4 block codec and
|
|
28
|
+
reads TOML with `tomllib`. Keep it that way; a tool that edits a browser's files must be auditable.
|
|
29
|
+
- **`model.apply_layout` is pure**: it returns a new session and a list of operation dicts and must not mutate its
|
|
30
|
+
input. Anything that touches the filesystem lives in `profile.py`, `config.py` or `cli.py`.
|
|
31
|
+
- **Safety invariants** (each has a test; do not weaken them): `apply` refuses while Zen runs; it backs up before
|
|
32
|
+
writing; it checks the result before and after; it never closes or deletes an open tab; `plan`/`dump` never write;
|
|
33
|
+
`keep_folders` are left byte-for-byte alone; applying the same config twice changes nothing.
|
|
34
|
+
- **Fixtures are synthetic** (`tests/helpers.py`). Never commit a real session file or a real favicon database: they
|
|
35
|
+
hold browsing history. Real ones go in `tests/fixtures/private/` (git-ignored).
|
|
36
|
+
- **When Zen's format changes**, update `docs/session-format.md` first, then the code, then `TESTED_ZEN` in
|
|
37
|
+
`src/zenform/__init__.py`. `check_session_shape` should fail loudly rather than guess.
|
|
38
|
+
- Run: `PYTHONPATH=src python3 -W error -m unittest discover -s tests` and `uvx ruff check .`.
|
zenform-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Cathal Killeen
|
|
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.
|
zenform-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: zenform
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Zen browser as code: keep your pins, essentials and folders in readable files, then plan and apply them.
|
|
5
|
+
Project-URL: Homepage, https://github.com/cathal-killeen/zenform
|
|
6
|
+
Project-URL: Source, https://github.com/cathal-killeen/zenform
|
|
7
|
+
Project-URL: Issues, https://github.com/cathal-killeen/zenform/issues
|
|
8
|
+
Author: Cathal Killeen
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: config-as-code,dotfiles,pinned-tabs,zen-browser
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Operating System :: MacOS
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Topic :: Utilities
|
|
17
|
+
Requires-Python: >=3.11
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
|
|
20
|
+
# zenform
|
|
21
|
+
|
|
22
|
+
**Zen browser as code.** Keep your sidebar (Essentials, pinned folders, pinned tabs, labels and icons) in small, readable files. See what applying them would change, then apply.
|
|
23
|
+
|
|
24
|
+
```console
|
|
25
|
+
$ zenform plan
|
|
26
|
+
+ 117 Exports [Now] https://tracker.example.com/browse/APP-117
|
|
27
|
+
~ 'Inbox - me@example.com - Mail' -> 'Mail' [essentials]
|
|
28
|
+
- unpin 'Old pin' (becomes an ordinary tab)
|
|
29
|
+
icons: 1 filled from the favicon database
|
|
30
|
+
|
|
31
|
+
This is a plan; nothing was written. Close Zen, then run `zenform apply`.
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
> **Status: alpha, and unofficial.** zenform is an independent tool and is not affiliated with Zen Browser. It edits an
|
|
35
|
+
> undocumented file that Zen can change in any release; see [Safety](#safety). Tested on macOS with Zen 1.24.3b.
|
|
36
|
+
|
|
37
|
+
## Why
|
|
38
|
+
|
|
39
|
+
- **Sync with git or a synced folder.** Your browser setup becomes a few text files you can version, review and share between machines. Syncing config files is safe; syncing the browser's own state files is not.
|
|
40
|
+
- **Readable.** One file per concern, TOML, one pin per line, so a diff shows exactly what changed.
|
|
41
|
+
- **Works with AI agents.** `dump` gives an agent the current state in the same format it edits, `plan --json` is a safe dry run it can read, and it never needs to touch your live profile. See [AGENTS.md](AGENTS.md).
|
|
42
|
+
|
|
43
|
+
## Install
|
|
44
|
+
|
|
45
|
+
```console
|
|
46
|
+
uv tool install zenform # or: pipx install zenform
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Python 3.11 or newer, no other dependencies. From source: `uv tool install git+https://github.com/cathal-killeen/zenform`.
|
|
50
|
+
|
|
51
|
+
## Use
|
|
52
|
+
|
|
53
|
+
```console
|
|
54
|
+
zenform dump --out ~/zen-config # write your current pins as a config directory (start here)
|
|
55
|
+
$EDITOR ~/zen-config/folders/10-*.toml
|
|
56
|
+
export ZENFORM_CONFIG=~/zen-config # or pass --config, or run from inside the directory
|
|
57
|
+
zenform plan # what would change; writes nothing
|
|
58
|
+
# quit Zen, then:
|
|
59
|
+
zenform apply # backs up, writes, reads back to check
|
|
60
|
+
zenform rollback # undo the last apply (Zen closed)
|
|
61
|
+
zenform doctor # profile, Zen version, session format, config
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## The config
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
zen-config/
|
|
68
|
+
zenform.toml workspace = "Work"; keep_folders = ["Pull Requests"]
|
|
69
|
+
essentials.toml the icon tiles
|
|
70
|
+
folders/
|
|
71
|
+
10-code.toml name = "Code"; pins = [ ... ] (folders appear in file-name order)
|
|
72
|
+
20-tickets.toml
|
|
73
|
+
loose.toml optional: pins outside any folder
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
```toml
|
|
77
|
+
# folders/10-code.toml
|
|
78
|
+
name = "Code"
|
|
79
|
+
|
|
80
|
+
pins = [
|
|
81
|
+
{label = "app MRs", url = "https://git.example.com/team/app/-/merge_requests"},
|
|
82
|
+
{label = "api MRs", url = "https://git.example.com/team/api/-/merge_requests"},
|
|
83
|
+
]
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
- **label**: what the sidebar shows; keep it to 14 characters or fewer (zenform warns).
|
|
87
|
+
- **url**: the pin's *home page*. A pin Zen already has with the same home URL keeps its history and icon, so reuse the URL `dump` printed for pins you keep.
|
|
88
|
+
- **keep_folders**: folders zenform leaves exactly as they are (for example folders Zen manages itself).
|
|
89
|
+
- Unknown keys are errors, so a typo does not silently do nothing.
|
|
90
|
+
|
|
91
|
+
See [`examples/config`](examples/config).
|
|
92
|
+
|
|
93
|
+
## What apply does and does not do
|
|
94
|
+
|
|
95
|
+
- Pins in the config are created, relabelled or moved. A pin the config no longer lists becomes an **ordinary tab; nothing is closed**. Open tabs are never edited.
|
|
96
|
+
- A pin with no icon is given one from your profile's favicon database (sites you have visited), so it is not blank until its page loads. If the site was never visited, it stays blank until opened once.
|
|
97
|
+
- Only the workspace named in `zenform.toml` is managed. Essentials span workspaces, so they are always managed.
|
|
98
|
+
|
|
99
|
+
## Safety
|
|
100
|
+
|
|
101
|
+
Zen keeps pins in `zen-sessions.jsonlz4` and rewrites it while running and on quit. So:
|
|
102
|
+
|
|
103
|
+
- `apply` **refuses to run while Zen is open**, backs the file up to `zenform-backups/` in the profile first, checks the result before writing and reads it back after, and restores the backup itself if that check fails.
|
|
104
|
+
- `plan` and `dump` only read. The favicon database is read from a copy.
|
|
105
|
+
- The format is undocumented ([what we know](docs/session-format.md)). `doctor` warns on a Zen version that has not been tested, and every command refuses a session file that does not have the expected shape.
|
|
106
|
+
- Do not put real session files in a public repo: they contain your tab history.
|
|
107
|
+
|
|
108
|
+
## Agents
|
|
109
|
+
|
|
110
|
+
Point an agent at the config directory and [AGENTS.md](AGENTS.md). The loop is: `zenform dump` for the current state, edit the files, `zenform plan --json` to check, and leave the `apply` to you.
|
|
111
|
+
|
|
112
|
+
## Development
|
|
113
|
+
|
|
114
|
+
```console
|
|
115
|
+
PYTHONPATH=src python3 -W error -m unittest discover -s tests
|
|
116
|
+
uvx ruff check .
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Standard library only, on purpose: it has to work on a bare machine, and a tool that edits your browser should be easy to audit.
|
|
120
|
+
|
|
121
|
+
## License
|
|
122
|
+
|
|
123
|
+
MIT
|
zenform-0.1.0/README.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# zenform
|
|
2
|
+
|
|
3
|
+
**Zen browser as code.** Keep your sidebar (Essentials, pinned folders, pinned tabs, labels and icons) in small, readable files. See what applying them would change, then apply.
|
|
4
|
+
|
|
5
|
+
```console
|
|
6
|
+
$ zenform plan
|
|
7
|
+
+ 117 Exports [Now] https://tracker.example.com/browse/APP-117
|
|
8
|
+
~ 'Inbox - me@example.com - Mail' -> 'Mail' [essentials]
|
|
9
|
+
- unpin 'Old pin' (becomes an ordinary tab)
|
|
10
|
+
icons: 1 filled from the favicon database
|
|
11
|
+
|
|
12
|
+
This is a plan; nothing was written. Close Zen, then run `zenform apply`.
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
> **Status: alpha, and unofficial.** zenform is an independent tool and is not affiliated with Zen Browser. It edits an
|
|
16
|
+
> undocumented file that Zen can change in any release; see [Safety](#safety). Tested on macOS with Zen 1.24.3b.
|
|
17
|
+
|
|
18
|
+
## Why
|
|
19
|
+
|
|
20
|
+
- **Sync with git or a synced folder.** Your browser setup becomes a few text files you can version, review and share between machines. Syncing config files is safe; syncing the browser's own state files is not.
|
|
21
|
+
- **Readable.** One file per concern, TOML, one pin per line, so a diff shows exactly what changed.
|
|
22
|
+
- **Works with AI agents.** `dump` gives an agent the current state in the same format it edits, `plan --json` is a safe dry run it can read, and it never needs to touch your live profile. See [AGENTS.md](AGENTS.md).
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```console
|
|
27
|
+
uv tool install zenform # or: pipx install zenform
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Python 3.11 or newer, no other dependencies. From source: `uv tool install git+https://github.com/cathal-killeen/zenform`.
|
|
31
|
+
|
|
32
|
+
## Use
|
|
33
|
+
|
|
34
|
+
```console
|
|
35
|
+
zenform dump --out ~/zen-config # write your current pins as a config directory (start here)
|
|
36
|
+
$EDITOR ~/zen-config/folders/10-*.toml
|
|
37
|
+
export ZENFORM_CONFIG=~/zen-config # or pass --config, or run from inside the directory
|
|
38
|
+
zenform plan # what would change; writes nothing
|
|
39
|
+
# quit Zen, then:
|
|
40
|
+
zenform apply # backs up, writes, reads back to check
|
|
41
|
+
zenform rollback # undo the last apply (Zen closed)
|
|
42
|
+
zenform doctor # profile, Zen version, session format, config
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## The config
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
zen-config/
|
|
49
|
+
zenform.toml workspace = "Work"; keep_folders = ["Pull Requests"]
|
|
50
|
+
essentials.toml the icon tiles
|
|
51
|
+
folders/
|
|
52
|
+
10-code.toml name = "Code"; pins = [ ... ] (folders appear in file-name order)
|
|
53
|
+
20-tickets.toml
|
|
54
|
+
loose.toml optional: pins outside any folder
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```toml
|
|
58
|
+
# folders/10-code.toml
|
|
59
|
+
name = "Code"
|
|
60
|
+
|
|
61
|
+
pins = [
|
|
62
|
+
{label = "app MRs", url = "https://git.example.com/team/app/-/merge_requests"},
|
|
63
|
+
{label = "api MRs", url = "https://git.example.com/team/api/-/merge_requests"},
|
|
64
|
+
]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
- **label**: what the sidebar shows; keep it to 14 characters or fewer (zenform warns).
|
|
68
|
+
- **url**: the pin's *home page*. A pin Zen already has with the same home URL keeps its history and icon, so reuse the URL `dump` printed for pins you keep.
|
|
69
|
+
- **keep_folders**: folders zenform leaves exactly as they are (for example folders Zen manages itself).
|
|
70
|
+
- Unknown keys are errors, so a typo does not silently do nothing.
|
|
71
|
+
|
|
72
|
+
See [`examples/config`](examples/config).
|
|
73
|
+
|
|
74
|
+
## What apply does and does not do
|
|
75
|
+
|
|
76
|
+
- Pins in the config are created, relabelled or moved. A pin the config no longer lists becomes an **ordinary tab; nothing is closed**. Open tabs are never edited.
|
|
77
|
+
- A pin with no icon is given one from your profile's favicon database (sites you have visited), so it is not blank until its page loads. If the site was never visited, it stays blank until opened once.
|
|
78
|
+
- Only the workspace named in `zenform.toml` is managed. Essentials span workspaces, so they are always managed.
|
|
79
|
+
|
|
80
|
+
## Safety
|
|
81
|
+
|
|
82
|
+
Zen keeps pins in `zen-sessions.jsonlz4` and rewrites it while running and on quit. So:
|
|
83
|
+
|
|
84
|
+
- `apply` **refuses to run while Zen is open**, backs the file up to `zenform-backups/` in the profile first, checks the result before writing and reads it back after, and restores the backup itself if that check fails.
|
|
85
|
+
- `plan` and `dump` only read. The favicon database is read from a copy.
|
|
86
|
+
- The format is undocumented ([what we know](docs/session-format.md)). `doctor` warns on a Zen version that has not been tested, and every command refuses a session file that does not have the expected shape.
|
|
87
|
+
- Do not put real session files in a public repo: they contain your tab history.
|
|
88
|
+
|
|
89
|
+
## Agents
|
|
90
|
+
|
|
91
|
+
Point an agent at the config directory and [AGENTS.md](AGENTS.md). The loop is: `zenform dump` for the current state, edit the files, `zenform plan --json` to check, and leave the `apply` to you.
|
|
92
|
+
|
|
93
|
+
## Development
|
|
94
|
+
|
|
95
|
+
```console
|
|
96
|
+
PYTHONPATH=src python3 -W error -m unittest discover -s tests
|
|
97
|
+
uvx ruff check .
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Standard library only, on purpose: it has to work on a bare machine, and a tool that edits your browser should be easy to audit.
|
|
101
|
+
|
|
102
|
+
## License
|
|
103
|
+
|
|
104
|
+
MIT
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# What zenform knows about Zen's session file
|
|
2
|
+
|
|
3
|
+
Zen keeps its sidebar (Essentials, pinned folders, pinned tabs) in `zen-sessions.jsonlz4` in the profile. This is
|
|
4
|
+
undocumented and can change in any Zen release. Everything below was found by reading real files, and is the reason
|
|
5
|
+
`zenform doctor` checks versions. Last checked against **Zen 1.24.3b** (Firefox platform 2026-11), macOS.
|
|
6
|
+
|
|
7
|
+
## The file
|
|
8
|
+
|
|
9
|
+
`mozLz40\0` (8 bytes) + little-endian uint32 uncompressed size + one LZ4 block of UTF-8 JSON. Zen rewrites it while
|
|
10
|
+
running and when it quits, so edits are only safe with Zen closed.
|
|
11
|
+
|
|
12
|
+
Top-level keys: `lastCollected`, `tabs`, `folders`, `splitViewData`, `groups`, `spaces`.
|
|
13
|
+
|
|
14
|
+
- `spaces[]` the workspaces: `{uuid, name, theme, containerTabId, ...}`.
|
|
15
|
+
- `folders[]` pinned folders: `{id, name, collapsed, workspaceId, prevSiblingInfo, emptyTabIds, ...}`. A folder's
|
|
16
|
+
order is a linked list: `prevSiblingInfo` is `null` for the first and `{"type": "group", "id": <previous>}` after.
|
|
17
|
+
- `groups[]` a parallel list with the same ids: `{id, name, color, collapsed, ...}`.
|
|
18
|
+
|
|
19
|
+
## Tabs (`tabs[]`)
|
|
20
|
+
|
|
21
|
+
A pinned tab is an ordinary tab entry with extra `zen*` fields:
|
|
22
|
+
|
|
23
|
+
| Field | Meaning |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `pinned` | true for any pin, Essentials included |
|
|
26
|
+
| `zenEssential` | true for an Essential (then `zenWorkspace` is `null`: Essentials span workspaces) |
|
|
27
|
+
| `zenWorkspace` | workspace uuid for a non-essential pin |
|
|
28
|
+
| `groupId` | the folder a pin is in (absent for a loose pin) |
|
|
29
|
+
| `zenStaticLabel` | the user-set label shown in the sidebar |
|
|
30
|
+
| `zenSyncId` | `<ms-timestamp>-<uuid>` |
|
|
31
|
+
| `_zenPinnedInitialState` | `{entry: {url, title}, image}`: the pin's home page; what "reset pin" returns to |
|
|
32
|
+
| `image` | the tab's icon as a `data:` URI |
|
|
33
|
+
| `entries[]`, `index` | the history of the tab and where it is in it (1-based) |
|
|
34
|
+
|
|
35
|
+
- **Home URL vs current page.** `entries[index-1]` is where the pin is now; `_zenPinnedInitialState.entry.url` is its
|
|
36
|
+
home. zenform identifies a pin by its home URL, so a pin keeps its history and icon across applies.
|
|
37
|
+
- **Folders hold an empty placeholder tab** (`zenIsEmpty: true`, `about:blank`) whose `zenSyncId` is listed in the
|
|
38
|
+
folder's `emptyTabIds`. Zen needs it; zenform keeps or creates it.
|
|
39
|
+
- **Order** is the order of `tabs[]`: Essentials, then each folder's placeholder and pins, then the rest.
|
|
40
|
+
- **Icons.** A pin Zen has not loaded has `image: null` and shows a blank icon until its page is opened. zenform fills
|
|
41
|
+
both `image` and `_zenPinnedInitialState.image` from `favicons.sqlite`.
|
|
42
|
+
|
|
43
|
+
## Not in this file
|
|
44
|
+
|
|
45
|
+
- Bookmarks (`places.sqlite`) are unrelated to pins.
|
|
46
|
+
- `zen-live-folders.jsonlz4` holds Zen's live folders. zenform does not manage them; list a folder in
|
|
47
|
+
`keep_folders` to leave it exactly as it is.
|
|
48
|
+
- Open (unpinned) tabs are in this file too but zenform never edits them. A pin the config drops is unpinned, not
|
|
49
|
+
closed.
|
|
50
|
+
|
|
51
|
+
## Favicons
|
|
52
|
+
|
|
53
|
+
`favicons.sqlite`: `moz_icons` (blob in `data`, `width`, `root`), `moz_pages_w_icons` (`page_url`),
|
|
54
|
+
`moz_icons_to_pages`. Lookup: the same page, else the closest page on the same site (longest shared path prefix),
|
|
55
|
+
else the site's root icon. Read from a copy, never the original.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# The part that goes stale: rebuild it from your tracker every month or quarter.
|
|
2
|
+
name = "Now"
|
|
3
|
+
|
|
4
|
+
pins = [
|
|
5
|
+
{label = "101 Login", url = "https://tracker.example.com/browse/APP-101"},
|
|
6
|
+
{label = "117 Exports", url = "https://tracker.example.com/browse/APP-117"},
|
|
7
|
+
]
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "zenform"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Zen browser as code: keep your pins, essentials and folders in readable files, then plan and apply them."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [{ name = "Cathal Killeen" }]
|
|
9
|
+
requires-python = ">=3.11"
|
|
10
|
+
keywords = ["zen-browser", "config-as-code", "dotfiles", "pinned-tabs"]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 3 - Alpha",
|
|
13
|
+
"Environment :: Console",
|
|
14
|
+
"Programming Language :: Python :: 3",
|
|
15
|
+
"Topic :: Utilities",
|
|
16
|
+
"Operating System :: MacOS",
|
|
17
|
+
]
|
|
18
|
+
dependencies = [] # standard library only, on purpose: see AGENTS.md
|
|
19
|
+
|
|
20
|
+
[project.scripts]
|
|
21
|
+
zenform = "zenform.cli:main"
|
|
22
|
+
|
|
23
|
+
[project.urls]
|
|
24
|
+
Homepage = "https://github.com/cathal-killeen/zenform"
|
|
25
|
+
Source = "https://github.com/cathal-killeen/zenform"
|
|
26
|
+
Issues = "https://github.com/cathal-killeen/zenform/issues"
|
|
27
|
+
|
|
28
|
+
[build-system]
|
|
29
|
+
requires = ["hatchling>=1.27"]
|
|
30
|
+
build-backend = "hatchling.build"
|
|
31
|
+
|
|
32
|
+
[tool.hatch.build.targets.wheel]
|
|
33
|
+
packages = ["src/zenform"]
|
|
34
|
+
|
|
35
|
+
[tool.ruff]
|
|
36
|
+
line-length = 120
|
|
37
|
+
target-version = "py311"
|
|
38
|
+
|
|
39
|
+
[tool.ruff.lint]
|
|
40
|
+
select = ["E", "F", "I", "UP", "B"]
|