Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: Bug report
description: Something in Foci isn't working the way it should
labels: [bug]
body:
- type: textarea
id: what
attributes:
label: What happened?
description: What did you expect, and what happened instead?
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
placeholder: |
1. Open Foci
2. Right-click a to-do → Schedule for Tomorrow
3. ...
validations:
required: true
- type: dropdown
id: how
attributes:
label: How do you run Foci?
options:
- From source (python main.py)
- Packaged .exe / app
validations:
required: true
- type: input
id: os
attributes:
label: OS and Python version
placeholder: Windows 11, Python 3.12
validations:
required: true
- type: textarea
id: logs
attributes:
label: Console output or screenshot
description: Anything printed in the terminal, or a screenshot of the problem. Remove anything personal.
render: text
1 change: 1 addition & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
blank_issues_enabled: true
22 changes: 22 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: Feature request
description: Suggest an idea for Foci
labels: [enhancement]
body:
- type: textarea
id: problem
attributes:
label: What would this help you do?
description: Describe the situation or frustration, not just the solution.
validations:
required: true
- type: textarea
id: idea
attributes:
label: What would you like to see?
validations:
required: true
- type: textarea
id: calm
attributes:
label: How does it keep Foci calm?
description: Foci tries to avoid noisy, guilt-inducing UI. Any thoughts on how this fits?
13 changes: 13 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
## What does this change?

<!-- One or two sentences. Link the issue it closes, e.g. "Closes #12". -->

## How did you test it?

- [ ] `pytest -q` passes
- [ ] `ruff check .` passes
- [ ] Ran the app and tried the change by hand

## Screenshots / GIF

<!-- Required for visual changes. -->
55 changes: 55 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
name: CI

on:
push:
branches: [main]
pull_request:

permissions:
contents: read

jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install ruff
- run: ruff check .

test:
name: test (${{ matrix.os }}, py${{ matrix.python-version }})
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
python-version: ["3.10", "3.13"]
env:
SDL_VIDEODRIVER: dummy
SDL_AUDIODRIVER: dummy
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
cache: pip
- run: pip install -r requirements.txt pytest
- run: pytest -q
- name: Smoke test (app starts headless)
shell: bash
run: |
python - <<'PY'
import os, subprocess, sys, tempfile
env = dict(os.environ, FOCI_DATA_DIR=tempfile.mkdtemp())
p = subprocess.Popen([sys.executable, "main.py"], env=env)
try:
code = p.wait(timeout=8)
except subprocess.TimeoutExpired:
p.kill()
print("main.py is running after 8s - OK")
else:
sys.exit(f"main.py exited early with code {code}")
PY
34 changes: 34 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Changelog

All notable changes to Foci are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## [Unreleased]

### Fixed
- **Packaged app lost all data on restart.** The one-file `.exe` wrote events, to-dos, settings and coins into PyInstaller's temporary extraction folder, which is deleted on exit. User data now lives in the OS app-data folder for packaged builds (`%APPDATA%\Foci` etc.) and stays in `assets/` when running from source.
- Launching `python path/to/main.py` from a different directory couldn't find fonts, icons or the coin sprite sheet. Resources now resolve relative to the app, not the working directory.
- "Schedule for Tomorrow" set the `tmr` tag and then immediately deleted it.
- Date tags didn't roll over for to-dos inside folders.
- "Delete completed" ignored completed to-dos inside folders.
- Google Calendar: fixed an import that always failed (`google.auth_oauthlib` → `google_auth_oauthlib`), the day window being computed in UTC instead of local time, event times not being converted to local time, and all-day events being imported as 24-hour blocks.
- `format_time` wrapped around for durations of 24 hours or more.
- An unreadable data file (e.g. wrong text encoding) no longer crashes startup.
- Packaged builds call `multiprocessing.freeze_support()` so the lofi player subprocess starts correctly.

### Added
- To-dos show a date pill (*Today*, *Tomorrow*, *on Mon*), red when overdue.
- `FOCI_DATA_DIR` environment variable to choose where data is stored.
- `foci_store.py`: persistence and validation split out of `main.py` so it can be tested.
- Test suite (`pytest`) and GitHub Actions CI on Windows, macOS and Linux.
- Contributor guide, issue templates and pull request template.

### Changed
- The built executable is named `Foci.exe` instead of `main.exe`.

## [1.0.0] - initial release

- Day timeline with drag-to-create, move and resize events
- Nested to-do list with folders
- Focus timer, lofi music player with Windows media-key integration
- 8 themes, font picker, confetti, coin rewards, stats and weekly view
- Local-first JSON storage, PyInstaller build
59 changes: 59 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Contributing to Foci

Thanks for your interest! Foci is a small, calm desktop planner, and contributions of any size are welcome: bug reports, typo fixes, new themes, or bigger features.

## Getting set up

```bash
git clone https://github.com/akshit-python-programmer/Foci.git
cd Foci
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt pytest ruff
python main.py
```

While you're developing, you can keep your real planner data out of the way by pointing Foci at a scratch folder:

```bash
FOCI_DATA_DIR=/tmp/foci-dev python main.py
```

## Before you open a pull request

```bash
ruff check .
pytest -q
```

CI runs both on Windows, macOS and Linux, and also checks that `main.py` starts in a headless window.

## Project layout

| File | What's in it |
|---|---|
| `main.py` | The app: theme table, game loop, all drawing and input handling |
| `foci_store.py` | Loading, saving and validating settings / events / to-dos. No pygame, fully unit-tested. **Put new data logic here.** |
| `utility.py` | Drawing and math helpers shared by the UI |
| `google_calendar.py` | Experimental Google Calendar sync |
| `progress.py` | Standalone focus-timer demo |
| `tests/` | pytest suite |
| `assets/` | Fonts, icons, music, and `*.example.json` data templates |

`main.py` opens a window as soon as it's imported, so it can't be unit-tested directly. If you're adding logic that doesn't need to draw anything (date math, data cleanup, sorting), put it in `foci_store.py` with a test and call it from `main.py`.

## Guidelines

- **Keep it calm.** Foci is meant for people who find most productivity apps overwhelming. New UI should be quiet: soft colours, gentle animation, nothing that nags or punishes.
- **Don't break people's data.** Anything that changes the JSON format must still load old files. `foci_store.sanitize_*` is where to add defaults for new fields.
- **Small PRs are easier to review.** One fix or feature per PR, with a short description of what changed and how you tested it.
- **Include a screenshot or GIF** for visual changes.
- For bugs, add a regression test in `tests/` when you can.

## Reporting bugs

Please open an issue using the bug report template and include your OS, Python version, and steps to reproduce. If the bug involves your data, attach a trimmed copy of the relevant JSON file (remove anything personal).

## Licence

By contributing you agree that your contributions are licensed under the [MIT License](LICENSE).
53 changes: 40 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@
![pygame](https://img.shields.io/badge/Built%20with-pygame-44cc11)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
![License](https://img.shields.io/badge/License-MIT-green)
[![CI](https://github.com/akshit-python-programmer/Foci/actions/workflows/ci.yml/badge.svg)](https://github.com/akshit-python-programmer/Foci/actions/workflows/ci.yml)
[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen)](CONTRIBUTING.md)

<div align="center">
<a href="docs/TECHNICAL.md">
Expand Down Expand Up @@ -62,22 +64,31 @@ To try just the standalone focus timer:
python progress.py
```

### Run the tests

```bash
pip install pytest
pytest -q
```

### Build a standalone .exe

```bash
pip install pyinstaller
pyinstaller main.spec
# output in dist/
# output: dist/Foci.exe
```

### Optional: Google Calendar sync

1. In [Google Cloud Console](https://console.cloud.google.com/), create an OAuth 2.0 Desktop client and enable the Calendar API.
2. Download `credentials.json` → place in `assets/`.
3. First run opens a browser to authorize; token stored locally as `assets/token.json`.
2. Download `credentials.json` → place it in your [data folder](#your-data) (`assets/` when running from source).
3. First run opens a browser to authorize; the token is stored next to it as `token.json`.

Both files are git-ignored and must never be committed.

> **Status: experimental.** `google_calendar.py` can pull a day's events from Google, but it isn't wired into the app's UI yet and pushing local changes back to Google isn't implemented. See the open issues if you'd like to help.

---

## Tech stack
Expand Down Expand Up @@ -112,10 +123,10 @@ Both files are git-ignored and must never be committed.

### Nested to-do list
- Flat tasks and collapsible folders (e.g. Physics → Kinematics → today's problems)
- Date tags: *today*, *tomorrow*, *someday* — tags roll forward automatically at midnight
- Drag-and-drop reordering within the list
- Date tags: *Today*, *Tomorrow*, *on Mon*. Shown as a pill on each to-do (red when overdue) and rolled forward automatically each day, including to-dos inside folders
- Drag a to-do onto the timeline to turn it into an event (drag-to-reorder within the list is not implemented yet)
- Right-click context menu to schedule a task (Today / Tomorrow / Someday)
- Delete completed tasks in bulk with one button
- Delete completed tasks in bulk with one button (including ones inside folders)

### Focus timer
- Click the ▶ button on any currently-active event to open a standalone focus timer popup
Expand Down Expand Up @@ -151,11 +162,11 @@ Both files are git-ignored and must never be committed.
- Scrollable modal: theme picker (shows each theme's actual colors as a preview), font picker, day start/end hour sliders, calendar zoom slider (30–80 px/hr), sound effects toggle, confetti toggle, lofi toggle

### Local-first & privacy
- All data lives in plain JSON files in `assets/`: `events.json`, `todos.json`, `settings.json`, `player_data.json`
- All data lives in plain JSON files on your machine: `events.json`, `todos.json`, `settings.json`, `player_data.json`
- Personal files are git-ignored; `*.example.json` templates are included
- Nothing is uploaded anywhere

### Optional: Google Calendar sync
### Optional: Google Calendar sync (experimental)
- `google_calendar.py` — standalone OAuth2 flow using `google-api-python-client`
- Bring your own `credentials.json` from Google Cloud Console; token is stored locally and never committed

Expand All @@ -165,12 +176,28 @@ Both files are git-ignored and must never be committed.

| File | Contents |
|---|---|
| `assets/settings.json` | Theme, day hours, zoom, toggles |
| `assets/todos.json` | To-do list and folder tree |
| `assets/events.json` | Scheduled calendar events |
| `assets/player_data.json` | Coin count |
| `settings.json` | Theme, day hours, zoom, toggles |
| `todos.json` | To-do list and folder tree |
| `events.json` | Scheduled calendar events |
| `player_data.json` | Coin count |

Where they live:

| How you run Foci | Data folder |
|---|---|
| From source (`python main.py`) | `assets/` in the repo |
| Packaged app on Windows | `%APPDATA%\Foci` |
| Packaged app on macOS | `~/Library/Application Support/Foci` |
| Packaged app on Linux | `$XDG_DATA_HOME/Foci` (default `~/.local/share/Foci`) |
| Any, with `FOCI_DATA_DIR` set | that folder |

The files in `assets/` are git-ignored. Copy an `*.example.json` to get started, or just run the app and it creates fresh files. Corrupt or hand-edited files are repaired field by field on load instead of crashing the app.

---

## Contributing

These are git-ignored. Copy an `*.example.json` to get started, or just run the app — it creates fresh files automatically.
Bug reports, ideas and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the project layout and how to run the tests. Changes are tracked in [CHANGELOG.md](CHANGELOG.md).

---

Expand Down
6 changes: 2 additions & 4 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# docs

Put screenshots and demo media here.
- [TECHNICAL.md](TECHNICAL.md): architecture and engineering notes.

The main README references `docs/demo.png` — drop a screenshot or short GIF of Foci
(e.g. dragging an event onto the timeline and checking off a task) at that path to make
the repo's landing page pop.
Screenshots and demo GIFs used by the main README live in [`../demo`](../demo).
7 changes: 5 additions & 2 deletions docs/TECHNICAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,18 @@ Foci is a single-process desktop app with one deliberate exception: the lofi mus
```
main.py (main process, 60 fps game loop)
│
├── foci_store.py persistence + validation (pure Python, no pygame, unit-tested)
├── utility.py helper functions (math, color, font cache, drawing primitives)
├── google_calendar.py optional OAuth2 calendar sync (self-contained)
├── google_calendar.py optional OAuth2 calendar sync (experimental, self-contained)
├── progress.py standalone focus-timer demo
│
└── subprocess: simple_music_player_process()
└── SMTCController WinRT media-key / tray integration
```

Data is stored in four plain JSON files in `assets/`. No database, no cloud, no framework.
Data is stored in four plain JSON files. No database, no cloud, no framework.

Bundled resources (fonts, icons, music) and user data are kept apart on purpose. `foci_store.app_root()` points at the read-only resources, which in a PyInstaller one-file build are unpacked to a temporary `sys._MEIPASS` folder that's deleted on exit. `foci_store.user_data_dir()` points at a writable per-user folder (`assets/` from source, the OS app-data folder when packaged, or `FOCI_DATA_DIR`). Every JSON write goes to a temp file first and then `os.replace()`s it, so a crash mid-save can't leave a half-written file.

---

Expand Down
Loading
Loading