projectum 1.6.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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 wleeaf
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.
@@ -0,0 +1,201 @@
1
+ Metadata-Version: 2.4
2
+ Name: projectum
3
+ Version: 1.6.0
4
+ Summary: Keyboard-first desktop tracker for the projects, playlists, and notes that live in a folder on your disk.
5
+ Author: wleeaf
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/wleeaf/projectum
8
+ Project-URL: Issues, https://github.com/wleeaf/projectum/issues
9
+ Keywords: pyside6,qt,project-tracker,notes,youtube,playlists
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Environment :: X11 Applications :: Qt
12
+ Classifier: Intended Audience :: End Users/Desktop
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Desktop Environment
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: PySide6>=6.5
24
+ Requires-Dist: yt-dlp>=2024.0
25
+ Dynamic: license-file
26
+
27
+ <div align="center">
28
+
29
+ # Projectum
30
+
31
+ **A keyboard-first desktop tracker for the projects, playlists, tasks, and notes that live in a folder on your disk.**
32
+
33
+ [![CI](https://github.com/wleeaf/projectum/actions/workflows/ci.yml/badge.svg)](https://github.com/wleeaf/projectum/actions/workflows/ci.yml)
34
+ [![Release](https://img.shields.io/github/v/release/wleeaf/projectum?sort=semver)](https://github.com/wleeaf/projectum/releases/latest)
35
+ [![Downloads](https://img.shields.io/github/downloads/wleeaf/projectum/total)](https://github.com/wleeaf/projectum/releases)
36
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
37
+ [![PySide6](https://img.shields.io/badge/PySide6-Qt%206-41cd52.svg)](https://doc.qt.io/qtforpython/)
38
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
39
+
40
+ No servers. No accounts. No telemetry. Your data is one JSON file next to your work.
41
+
42
+ ![Projectum — projects view](docs/screenshots/01-projects.png)
43
+
44
+ </div>
45
+
46
+ ---
47
+
48
+ ## What it is
49
+
50
+ Point Projectum at a folder and **every subfolder becomes a project** you can mark *done* and *tested*, tag with colors, annotate with live‑rendered Markdown, pin, and reorder. The same window tracks **YouTube playlists** — titles, durations, watched state, and per‑video notes via [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) — keeps a **to‑do list** and a **folder‑wide scratchpad**. A `Ctrl+K` command palette searches across all of it.
51
+
52
+ Everything for a folder is stored in a single, human‑readable `.projectum.json` inside it — so it travels with your work, diffs cleanly in Git, and is trivial to back up or delete.
53
+
54
+ ## Download
55
+
56
+ ### Linux — AppImage (recommended)
57
+
58
+ Grab the latest self‑contained build, mark it executable, and run it. No Python, no `pip`, nothing to install.
59
+
60
+ ```bash
61
+ wget https://github.com/wleeaf/projectum/releases/latest/download/Projectum-x86_64.AppImage
62
+ chmod +x Projectum-x86_64.AppImage
63
+ ./Projectum-x86_64.AppImage
64
+ ```
65
+
66
+ The AppImage bundles Python, Qt, PySide6, and `yt-dlp`, and runs on any reasonably modern x86‑64 desktop (glibc ≥ 2.17).
67
+
68
+ ### Windows & macOS
69
+
70
+ Grab `Projectum-windows-x64.exe` or `Projectum-macos.dmg` from the [latest release](https://github.com/wleeaf/projectum/releases/latest).
71
+
72
+ > **Note:** these builds are **unsigned**, so the OS will warn on first launch.
73
+ > - **Windows:** SmartScreen → **More info → Run anyway**.
74
+ > - **macOS:** right‑click the app → **Open** (or System Settings → Privacy & Security → **Open Anyway**).
75
+ >
76
+ > If in doubt, running from source (below) avoids the warnings entirely.
77
+
78
+ ### From source (Linux · macOS · Windows)
79
+
80
+ Requires **Python ≥ 3.10**.
81
+
82
+ ```bash
83
+ git clone https://github.com/wleeaf/projectum.git
84
+ cd projectum
85
+ python -m venv .venv
86
+ source .venv/bin/activate # Windows: .venv\Scripts\activate
87
+ pip install -r requirements.txt
88
+ python main.py # or: python main.py ~/code
89
+ ```
90
+
91
+ Projectum remembers the last folder you opened, so later launches go straight back to it.
92
+
93
+ ## Features
94
+
95
+ - **Filesystem‑backed projects.** Any folder works; each subfolder is a project. State lives in one `.projectum.json` per folder — Git‑friendly, sync‑friendly, no database.
96
+ - **YouTube playlists with per‑video tracking.** Paste a URL, `yt-dlp` fetches the metadata, tick videos off as you watch, and keep notes per video. *Refresh* later pulls in new uploads while preserving your progress; videos removed upstream are kept and flagged.
97
+ - **Live WYSIWYG Markdown** in every notes pane. Headings, bold/italic, inline and fenced code, lists, blockquotes, strikethrough, and links render as you type — the syntax markers stay dimmed but present, so it's still plain editable Markdown with no separate preview.
98
+ - **A folder-scoped Todo list** — quick tasks per folder: add, check off, double‑click to edit inline, delete, and drag to reorder, with a done/total counter.
99
+ - **Project quick-actions** — right‑click a project to open its folder, copy its path, open a terminal there, or open it in your editor (VS Code / Cursor / Zed / Sublime when on `PATH`).
100
+ - **Git-aware** — the detail panel shows a project's current branch and whether its working tree is dirty, read off the UI thread.
101
+ - **Recent-folders menu** — a **Recent ▾** button to jump back between the folders you track.
102
+ - **Tags with custom colors** (right‑click any chip), an automatic cleanup that drops unused colors, and a sidebar tag filter.
103
+ - **Done + Tested toggles** per project — a green check and a blue one; tested projects render in blue in the sidebar.
104
+ - **Pin & drag‑to‑reorder** projects and playlists; pinned items float to the top.
105
+ - **Command palette (`Ctrl+K`)** over projects, playlists, videos, tags, and the scratchpad, with prefix‑match ranking and type‑ahead.
106
+ - **19 built‑in themes** spanning the spectrum — distinctive ones like **Midnight** (true‑black OLED), **Synthwave** (neon), **Ember** (warm orange‑red), **Graphite** (colorless mono) and **Paper** (crisp white) alongside Catppuccin Mocha / Latte / Macchiato, Nord, Dracula, Tokyo Night, Rosé Pine, One Dark, GitHub Dark, Everforest, Gruvbox Dark / Light, and Solarized Dark / Light. Every theme is held to a WCAG contrast bar so text stays readable, previewed by a color swatch in the picker, and crossfaded when you switch. Plus **any installed font** at any size.
107
+ - **Frameless, animated UI** with smooth wheel scrolling, custom title bar, edge‑resize, and flicker‑free crossfade transitions.
108
+ - **Resilient state.** Writes are atomic; a folder that disappears (rename, `git checkout`) has its metadata preserved and restored when it returns.
109
+
110
+ ## Screenshots
111
+
112
+ | | |
113
+ |---|---|
114
+ | **Projects** — tagged, pinned, tested<br>![Projects](docs/screenshots/01-projects.png) | **Playlists** — videos, watched count, notes<br>![Playlists](docs/screenshots/02-playlists.png) |
115
+ | **Notes** — folder‑wide scratchpad, live Markdown<br>![Notes](docs/screenshots/03-notes-preview.png) | **Command palette** — `Ctrl+K` over everything<br>![Palette](docs/screenshots/04-command-palette.png) |
116
+ | **Settings** — theme, font family, font size<br>![Settings](docs/screenshots/05-settings.png) | **Light theme** — same app, Catppuccin Latte<br>![Light](docs/screenshots/06-light-theme.png) |
117
+
118
+ ## Usage
119
+
120
+ **Projects** — Each subfolder of the chosen root is a row. Toggle **done** (green) or **tested** (blue); tested projects show their name in blue. Tags are inline chips — right‑click to recolor, click the **×** to remove, and filter by tag from the **Tag** chip at the top of the sidebar. Drag rows to reorder, or right‑click for **Pin to top** and quick actions (**Open folder / Copy path / Open in terminal / Open in editor**). The detail panel shows the folder's size, last‑modified time, and **git branch + dirty state**; the notes editor renders Markdown live, in place.
121
+
122
+ **Playlists** — **+ Add YouTube playlist** prompts for a URL; `yt-dlp` fetches the title, uploader, and every video. **Refresh** re‑syncs while keeping your watched/notes state. Tag, pin, reorder, and write per‑playlist notes; each video has its own notes pane below the list.
123
+
124
+ **Todo** — A folder‑scoped task list. Type a task and press Enter to add it; tick the toggle to complete it (it strikes through), double‑click the text to edit inline, drag to reorder, and use the **×** to delete. A counter shows how many are done.
125
+
126
+ **Notes** — A single, folder‑wide scratchpad with live WYSIWYG Markdown and a search bar (`↵` / `Shift+↵` to jump between matches).
127
+
128
+ **Command palette** — `Ctrl+K` from anywhere. Type to filter projects, playlists, videos, tags, and the scratchpad; `↑`/`↓` to navigate, `↵` to open, `Esc` to dismiss.
129
+
130
+ **Settings** — The gear icon opens dropdowns for theme (each previewed with a color swatch), font family (select-only, every family shown in its own font), and font size (preset pixels). Changes are staged and applied only when you click **Apply**, then persist across launches.
131
+
132
+ ## Keyboard shortcuts
133
+
134
+ | Shortcut | Action |
135
+ |-------------------|-------------------------------------------------|
136
+ | `Ctrl+K` | Open the command palette |
137
+ | `Ctrl+1` … `Ctrl+4` | Switch tab (Projects / Playlists / Todo / Notes) |
138
+ | `Ctrl+O` | Open a folder |
139
+ | `Ctrl+F` | Focus the sidebar search |
140
+ | `Ctrl+D` | Toggle the selected project's *done* state |
141
+ | `Ctrl+T` | Jump to Todo and start a new task |
142
+ | `Ctrl+N` | Focus the project notes editor |
143
+ | `Ctrl+R` | Refresh the current folder |
144
+ | `↵` / `Shift+↵` | Next / previous match in Notes search |
145
+ | `Esc` | Close a popup (color picker, settings, palette) |
146
+
147
+ ## Data & storage
148
+
149
+ All state for a folder lives in `<folder>/.projectum.json` — a single JSON document holding projects, playlists, tags, notes, pins, and ordering. Commit it alongside your work or `.gitignore` it; it's yours. Writes are atomic (write‑temp‑then‑rename), so an interrupted save never corrupts the file.
150
+
151
+ The only thing written outside your folders is `~/.config/projectum/state.json` (or `$XDG_CONFIG_HOME`), which remembers your window geometry, last‑opened folder, and theme/font settings.
152
+
153
+ When a project folder disappears (rename, branch switch), its metadata — completion, notes, tags, pins, order — is parked in an `_orphans` bucket and restored intact if the folder reappears.
154
+
155
+ ## Project layout
156
+
157
+ ```
158
+ projectum/
159
+ ├── main.py # entry point
160
+ ├── projectum/
161
+ │ ├── app.py # MainWindow + run()
162
+ │ ├── store.py # Project / Playlist / Video / ProjectStore
163
+ │ ├── widgets.py # custom-painted widgets (chips, toggles, palette, …)
164
+ │ ├── theme.py # 19 themes + contrast helpers + stylesheet builder
165
+ │ ├── anims.py # crossfade / slide / progress / smooth-scroll helpers
166
+ │ ├── youtube.py # yt-dlp fetch runnable
167
+ │ └── assets/icon.svg
168
+ ├── packaging/appimage/ # AppImage recipe + build script
169
+ ├── .github/workflows/ # CI + release (AppImage) pipelines
170
+ ├── requirements.txt
171
+ └── docs/screenshots/
172
+ ```
173
+
174
+ ## Development
175
+
176
+ ```bash
177
+ python -m venv .venv && source .venv/bin/activate
178
+ pip install -r requirements.txt
179
+ python main.py
180
+ ```
181
+
182
+ The codebase is deliberately dependency‑light: `PySide6` for the UI, `yt-dlp` for playlist metadata, and the standard library for everything else. Continuous integration runs `ruff`, byte‑compiles every module, runs the headless `pytest` suite, and boots `MainWindow` on an `offscreen` display across Python 3.10–3.12 on Linux, macOS, and Windows.
183
+
184
+ Run the tests locally with:
185
+
186
+ ```bash
187
+ pip install pytest
188
+ QT_QPA_PLATFORM=offscreen pytest -q
189
+ ```
190
+
191
+ ### Building the AppImage locally
192
+
193
+ ```bash
194
+ pip install python-appimage build
195
+ ./packaging/appimage/build-appimage.sh
196
+ # -> build/appimage/Projectum-x86_64.AppImage
197
+ ```
198
+
199
+ ## License
200
+
201
+ [MIT](LICENSE) — © 2026 wleeaf.
@@ -0,0 +1,175 @@
1
+ <div align="center">
2
+
3
+ # Projectum
4
+
5
+ **A keyboard-first desktop tracker for the projects, playlists, tasks, and notes that live in a folder on your disk.**
6
+
7
+ [![CI](https://github.com/wleeaf/projectum/actions/workflows/ci.yml/badge.svg)](https://github.com/wleeaf/projectum/actions/workflows/ci.yml)
8
+ [![Release](https://img.shields.io/github/v/release/wleeaf/projectum?sort=semver)](https://github.com/wleeaf/projectum/releases/latest)
9
+ [![Downloads](https://img.shields.io/github/downloads/wleeaf/projectum/total)](https://github.com/wleeaf/projectum/releases)
10
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
11
+ [![PySide6](https://img.shields.io/badge/PySide6-Qt%206-41cd52.svg)](https://doc.qt.io/qtforpython/)
12
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
13
+
14
+ No servers. No accounts. No telemetry. Your data is one JSON file next to your work.
15
+
16
+ ![Projectum — projects view](docs/screenshots/01-projects.png)
17
+
18
+ </div>
19
+
20
+ ---
21
+
22
+ ## What it is
23
+
24
+ Point Projectum at a folder and **every subfolder becomes a project** you can mark *done* and *tested*, tag with colors, annotate with live‑rendered Markdown, pin, and reorder. The same window tracks **YouTube playlists** — titles, durations, watched state, and per‑video notes via [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) — keeps a **to‑do list** and a **folder‑wide scratchpad**. A `Ctrl+K` command palette searches across all of it.
25
+
26
+ Everything for a folder is stored in a single, human‑readable `.projectum.json` inside it — so it travels with your work, diffs cleanly in Git, and is trivial to back up or delete.
27
+
28
+ ## Download
29
+
30
+ ### Linux — AppImage (recommended)
31
+
32
+ Grab the latest self‑contained build, mark it executable, and run it. No Python, no `pip`, nothing to install.
33
+
34
+ ```bash
35
+ wget https://github.com/wleeaf/projectum/releases/latest/download/Projectum-x86_64.AppImage
36
+ chmod +x Projectum-x86_64.AppImage
37
+ ./Projectum-x86_64.AppImage
38
+ ```
39
+
40
+ The AppImage bundles Python, Qt, PySide6, and `yt-dlp`, and runs on any reasonably modern x86‑64 desktop (glibc ≥ 2.17).
41
+
42
+ ### Windows & macOS
43
+
44
+ Grab `Projectum-windows-x64.exe` or `Projectum-macos.dmg` from the [latest release](https://github.com/wleeaf/projectum/releases/latest).
45
+
46
+ > **Note:** these builds are **unsigned**, so the OS will warn on first launch.
47
+ > - **Windows:** SmartScreen → **More info → Run anyway**.
48
+ > - **macOS:** right‑click the app → **Open** (or System Settings → Privacy & Security → **Open Anyway**).
49
+ >
50
+ > If in doubt, running from source (below) avoids the warnings entirely.
51
+
52
+ ### From source (Linux · macOS · Windows)
53
+
54
+ Requires **Python ≥ 3.10**.
55
+
56
+ ```bash
57
+ git clone https://github.com/wleeaf/projectum.git
58
+ cd projectum
59
+ python -m venv .venv
60
+ source .venv/bin/activate # Windows: .venv\Scripts\activate
61
+ pip install -r requirements.txt
62
+ python main.py # or: python main.py ~/code
63
+ ```
64
+
65
+ Projectum remembers the last folder you opened, so later launches go straight back to it.
66
+
67
+ ## Features
68
+
69
+ - **Filesystem‑backed projects.** Any folder works; each subfolder is a project. State lives in one `.projectum.json` per folder — Git‑friendly, sync‑friendly, no database.
70
+ - **YouTube playlists with per‑video tracking.** Paste a URL, `yt-dlp` fetches the metadata, tick videos off as you watch, and keep notes per video. *Refresh* later pulls in new uploads while preserving your progress; videos removed upstream are kept and flagged.
71
+ - **Live WYSIWYG Markdown** in every notes pane. Headings, bold/italic, inline and fenced code, lists, blockquotes, strikethrough, and links render as you type — the syntax markers stay dimmed but present, so it's still plain editable Markdown with no separate preview.
72
+ - **A folder-scoped Todo list** — quick tasks per folder: add, check off, double‑click to edit inline, delete, and drag to reorder, with a done/total counter.
73
+ - **Project quick-actions** — right‑click a project to open its folder, copy its path, open a terminal there, or open it in your editor (VS Code / Cursor / Zed / Sublime when on `PATH`).
74
+ - **Git-aware** — the detail panel shows a project's current branch and whether its working tree is dirty, read off the UI thread.
75
+ - **Recent-folders menu** — a **Recent ▾** button to jump back between the folders you track.
76
+ - **Tags with custom colors** (right‑click any chip), an automatic cleanup that drops unused colors, and a sidebar tag filter.
77
+ - **Done + Tested toggles** per project — a green check and a blue one; tested projects render in blue in the sidebar.
78
+ - **Pin & drag‑to‑reorder** projects and playlists; pinned items float to the top.
79
+ - **Command palette (`Ctrl+K`)** over projects, playlists, videos, tags, and the scratchpad, with prefix‑match ranking and type‑ahead.
80
+ - **19 built‑in themes** spanning the spectrum — distinctive ones like **Midnight** (true‑black OLED), **Synthwave** (neon), **Ember** (warm orange‑red), **Graphite** (colorless mono) and **Paper** (crisp white) alongside Catppuccin Mocha / Latte / Macchiato, Nord, Dracula, Tokyo Night, Rosé Pine, One Dark, GitHub Dark, Everforest, Gruvbox Dark / Light, and Solarized Dark / Light. Every theme is held to a WCAG contrast bar so text stays readable, previewed by a color swatch in the picker, and crossfaded when you switch. Plus **any installed font** at any size.
81
+ - **Frameless, animated UI** with smooth wheel scrolling, custom title bar, edge‑resize, and flicker‑free crossfade transitions.
82
+ - **Resilient state.** Writes are atomic; a folder that disappears (rename, `git checkout`) has its metadata preserved and restored when it returns.
83
+
84
+ ## Screenshots
85
+
86
+ | | |
87
+ |---|---|
88
+ | **Projects** — tagged, pinned, tested<br>![Projects](docs/screenshots/01-projects.png) | **Playlists** — videos, watched count, notes<br>![Playlists](docs/screenshots/02-playlists.png) |
89
+ | **Notes** — folder‑wide scratchpad, live Markdown<br>![Notes](docs/screenshots/03-notes-preview.png) | **Command palette** — `Ctrl+K` over everything<br>![Palette](docs/screenshots/04-command-palette.png) |
90
+ | **Settings** — theme, font family, font size<br>![Settings](docs/screenshots/05-settings.png) | **Light theme** — same app, Catppuccin Latte<br>![Light](docs/screenshots/06-light-theme.png) |
91
+
92
+ ## Usage
93
+
94
+ **Projects** — Each subfolder of the chosen root is a row. Toggle **done** (green) or **tested** (blue); tested projects show their name in blue. Tags are inline chips — right‑click to recolor, click the **×** to remove, and filter by tag from the **Tag** chip at the top of the sidebar. Drag rows to reorder, or right‑click for **Pin to top** and quick actions (**Open folder / Copy path / Open in terminal / Open in editor**). The detail panel shows the folder's size, last‑modified time, and **git branch + dirty state**; the notes editor renders Markdown live, in place.
95
+
96
+ **Playlists** — **+ Add YouTube playlist** prompts for a URL; `yt-dlp` fetches the title, uploader, and every video. **Refresh** re‑syncs while keeping your watched/notes state. Tag, pin, reorder, and write per‑playlist notes; each video has its own notes pane below the list.
97
+
98
+ **Todo** — A folder‑scoped task list. Type a task and press Enter to add it; tick the toggle to complete it (it strikes through), double‑click the text to edit inline, drag to reorder, and use the **×** to delete. A counter shows how many are done.
99
+
100
+ **Notes** — A single, folder‑wide scratchpad with live WYSIWYG Markdown and a search bar (`↵` / `Shift+↵` to jump between matches).
101
+
102
+ **Command palette** — `Ctrl+K` from anywhere. Type to filter projects, playlists, videos, tags, and the scratchpad; `↑`/`↓` to navigate, `↵` to open, `Esc` to dismiss.
103
+
104
+ **Settings** — The gear icon opens dropdowns for theme (each previewed with a color swatch), font family (select-only, every family shown in its own font), and font size (preset pixels). Changes are staged and applied only when you click **Apply**, then persist across launches.
105
+
106
+ ## Keyboard shortcuts
107
+
108
+ | Shortcut | Action |
109
+ |-------------------|-------------------------------------------------|
110
+ | `Ctrl+K` | Open the command palette |
111
+ | `Ctrl+1` … `Ctrl+4` | Switch tab (Projects / Playlists / Todo / Notes) |
112
+ | `Ctrl+O` | Open a folder |
113
+ | `Ctrl+F` | Focus the sidebar search |
114
+ | `Ctrl+D` | Toggle the selected project's *done* state |
115
+ | `Ctrl+T` | Jump to Todo and start a new task |
116
+ | `Ctrl+N` | Focus the project notes editor |
117
+ | `Ctrl+R` | Refresh the current folder |
118
+ | `↵` / `Shift+↵` | Next / previous match in Notes search |
119
+ | `Esc` | Close a popup (color picker, settings, palette) |
120
+
121
+ ## Data & storage
122
+
123
+ All state for a folder lives in `<folder>/.projectum.json` — a single JSON document holding projects, playlists, tags, notes, pins, and ordering. Commit it alongside your work or `.gitignore` it; it's yours. Writes are atomic (write‑temp‑then‑rename), so an interrupted save never corrupts the file.
124
+
125
+ The only thing written outside your folders is `~/.config/projectum/state.json` (or `$XDG_CONFIG_HOME`), which remembers your window geometry, last‑opened folder, and theme/font settings.
126
+
127
+ When a project folder disappears (rename, branch switch), its metadata — completion, notes, tags, pins, order — is parked in an `_orphans` bucket and restored intact if the folder reappears.
128
+
129
+ ## Project layout
130
+
131
+ ```
132
+ projectum/
133
+ ├── main.py # entry point
134
+ ├── projectum/
135
+ │ ├── app.py # MainWindow + run()
136
+ │ ├── store.py # Project / Playlist / Video / ProjectStore
137
+ │ ├── widgets.py # custom-painted widgets (chips, toggles, palette, …)
138
+ │ ├── theme.py # 19 themes + contrast helpers + stylesheet builder
139
+ │ ├── anims.py # crossfade / slide / progress / smooth-scroll helpers
140
+ │ ├── youtube.py # yt-dlp fetch runnable
141
+ │ └── assets/icon.svg
142
+ ├── packaging/appimage/ # AppImage recipe + build script
143
+ ├── .github/workflows/ # CI + release (AppImage) pipelines
144
+ ├── requirements.txt
145
+ └── docs/screenshots/
146
+ ```
147
+
148
+ ## Development
149
+
150
+ ```bash
151
+ python -m venv .venv && source .venv/bin/activate
152
+ pip install -r requirements.txt
153
+ python main.py
154
+ ```
155
+
156
+ The codebase is deliberately dependency‑light: `PySide6` for the UI, `yt-dlp` for playlist metadata, and the standard library for everything else. Continuous integration runs `ruff`, byte‑compiles every module, runs the headless `pytest` suite, and boots `MainWindow` on an `offscreen` display across Python 3.10–3.12 on Linux, macOS, and Windows.
157
+
158
+ Run the tests locally with:
159
+
160
+ ```bash
161
+ pip install pytest
162
+ QT_QPA_PLATFORM=offscreen pytest -q
163
+ ```
164
+
165
+ ### Building the AppImage locally
166
+
167
+ ```bash
168
+ pip install python-appimage build
169
+ ./packaging/appimage/build-appimage.sh
170
+ # -> build/appimage/Projectum-x86_64.AppImage
171
+ ```
172
+
173
+ ## License
174
+
175
+ [MIT](LICENSE) — © 2026 wleeaf.
@@ -0,0 +1,4 @@
1
+ """Projectum — track every project in one place. Made by wleeaf."""
2
+
3
+ __version__ = "1.6.0"
4
+ __author__ = "wleeaf"