fuso 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '079729abca60749f7ed805ad7acad6127d8858781e0a520182e1e3db70d80488'
+  data.tar.gz: 5af2c50fe031ea9e551a5d97cb9a2ce3cb6a3e94028306ff896e5bd0aa667cba
+SHA512:
+  metadata.gz: 97151b014221fd818cebb75c4c4e0796a5b955d3e08e4ca8ff7227185c165673fc9775d429d441fd5afceba8ced8c133496b3cf902c0f874caab8964e7acc081
+  data.tar.gz: 1b2cf8b7a3ca6f212c681150e41dce076d15a9f7f41db4b6aa209c36960106d53ba24ea845d0946557aaa244c52aacd7df4ee2fa9b5885bf6876e40b53bf8bde

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Afonso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,242 @@
+<h1 align="center">Fuso</h1>
+<p align="center">
+  <em>A dead-simple terminal time tracker.<br>One key to start. One key to switch. One key to stop.</em>
+</p>
+
+<p align="center">
+  <a href="#installation">Install</a> ·
+  <a href="#usage">Usage</a> ·
+  <a href="#reports">Reports</a> ·
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+Most time tracking tools are either clunky web apps that demand your attention, or over-engineered CLIs with a dozen subcommands and flags. You just want to press **one key** when you sit down, and another key when you switch tasks. That's it.
+
+**Fuso** is a terminal-native time tracker that lives in your terminal and gets out of your way. No accounts. No cloud. No config files to learn. You open it, press `s`, and you're tracking. Press `3` to switch to "Meeting." Press `s` again to stop. Done.
+
+Your data is yours - plain JSON files in `~/.fuso/`.
+
+## Screenshots
+
+<p align="center">
+  <img src="assets/screenshot_tracking.png" alt="Fuso — active tracking" width="480">
+</p>
+<p align="center"><em>Tracking time with live category breakdown and per-category totals.</em></p>
+
+<p align="center">
+  <img src="assets/screenshot_report.png" alt="Fuso — weekly report" width="480">
+</p>
+<p align="center"><em>Weekly and monthly reports with CSV export.</em></p>
+
+## Features
+
+- **One-key workflow** — `s` to start/stop, `1`–`9` to switch categories, `p` to switch projects
+- **Minimalist TUI** — only what matters is on screen, nothing else
+- **Offline & private** — all data stored locally in `~/.fuso/` as plain JSON
+- **Suspend-safe** — if your laptop sleeps or hibernates, the timer stops automatically at the last known time (works in WSL too)
+- **CSV export** — weekly and monthly reports, ready for timesheets or invoicing
+- **Zero config** — sensible defaults on first run, customize via the built-in settings screen
+
+## Installation
+
+### Requirements
+
+- **Ruby 3.2+** (Ruby 4.0+ recommended)
+- A terminal with 256-color support
+
+### From RubyGems
+
+```bash
+gem install fuso
+```
+
+That's it. Now run `fuso` from anywhere.
+
+### From source
+
+```bash
+git clone https://github.com/AfonsoNeto/fuso-tui.git
+cd fuso-tui
+bundle install
+bundle exec exe/fuso
+```
+
+## Usage
+
+### Quick Start
+
+1. Launch `fuso`
+2. Press `s` to start tracking
+3. Press `1`–`9` to switch between categories
+4. Press `s` to stop
+5. Press `r` to view reports
+
+That's it. No flags, no subcommands, no YAML.
+
+### Typical Workflow
+
+Imagine you're a developer working on two projects. You open Fuso in the morning:
+
+```
+→ Press s to start tracking "Development" on "Project Alpha"
+→ A meeting starts — press 3 to switch to "Meeting"
+  (Development time is saved automatically)
+→ Meeting ends — press 1 to switch back to "Development"
+→ Need to help a colleague — press 4 for "Support"
+→ End of day — press s to stop
+→ Press r then e to export your timesheet as CSV
+```
+
+Every category switch is a single keypress. No interruptions. No context switching away from your terminal.
+
+### Use Cases
+
+| Scenario | How Fuso Helps |
+|----------|---------------|
+| **Freelancer billing** | Track hours per project/category, export CSV for invoicing |
+| **Team standups** | Glance at yesterday's breakdown before standup |
+| **Focus tracking** | See where your time actually goes vs. where you think it goes |
+| **Contractor timesheets** | Monthly reports with weekly breakdown, ready for submission |
+
+## Keyboard Shortcuts
+
+### Main Screen
+
+| Key | Action |
+|-----|--------|
+| `s` / `Space` | Start or stop the timer |
+| `1`–`9` | Switch to category by number |
+| `p` | Cycle through projects |
+| `m` | Open settings (manage projects & categories) |
+| `r` | Open reports |
+| `q` / `Ctrl+C` | Quit (active session is saved automatically) |
+
+### Settings Screen
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate list |
+| `Tab` | Switch between projects and categories |
+| `a` | Add new item |
+| `d` | Set selected item as default |
+| `x` | Delete selected item |
+| `Esc` | Back to main screen |
+
+### Reports Screen
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Toggle between weekly and monthly view |
+| `←` / `→` | Navigate between weeks or months |
+| `e` | Export current view as CSV |
+| `Esc` | Back to main screen |
+
+## Reports
+
+### In-App Reports
+
+Press `r` to open the report view. Use `Tab` to switch between weekly and monthly breakdowns. Navigate with `←` / `→`.
+
+### CSV Export
+
+Press `e` on the report screen to export. Files are saved to `~/.fuso/exports/`:
+
+```
+~/.fuso/exports/fuso_weekly_2026-W25.csv
+~/.fuso/exports/fuso_monthly_2026-06.csv
+```
+
+The monthly CSV includes a weekly breakdown with columns for each week-ending date, matching a standard timesheet format.
+
+### CLI Reports
+
+You can also view reports without the TUI:
+
+```bash
+fuso report weekly   # Current week summary
+fuso report monthly  # Current month summary
+```
+
+## Data Storage
+
+All data lives in `~/.fuso/`:
+
+```
+~/.fuso/
+├── config.json     # Projects, categories, defaults
+├── sessions.json   # All time entries, keyed by date
+├── heartbeat       # Active tracking timestamp (auto-cleaned)
+└── exports/        # Exported CSV files
+```
+
+Everything is plain JSON. You can read it, edit it, back it up, or sync it however you want.
+
+## How Suspend Recovery Works
+
+If your laptop goes to sleep, hibernates, or suspends — or if you close the lid and come back later — Fuso won't count the sleep time as work.
+
+While the timer is running, Fuso writes a heartbeat timestamp to `~/.fuso/heartbeat` every 10 seconds. When it wakes up and notices the gap is too large (>60s), it saves the session at the last known heartbeat time and stops the timer.
+
+This works everywhere: native Linux, WSL, macOS — no D-Bus, no systemd, no OS-specific APIs needed.
+
+## Built With
+
+- [Ruby](https://www.ruby-lang.org/) — simple, readable, gets the job done
+- [Charm Ruby](https://charm-ruby.dev/) — `bubbletea` (Elm Architecture TUI), `lipgloss` (styling), `bubbles` (components)
+
+## Contributing
+
+Contributions are welcome! Whether it's bug fixes, new features, documentation improvements, or just ideas — all are appreciated.
+
+### Getting Started
+
+```bash
+# Clone the repo
+git clone https://github.com/AfonsoNeto/fuso-tui.git
+cd fuso-tui
+
+# Install dependencies
+bundle install
+
+# Run the test suite
+bundle exec rake test
+
+# Launch the app
+bundle exec exe/fuso
+```
+
+### Running Tests
+
+The project uses [Minitest](https://github.com/minitest/minitest). All tests run in an isolated temporary directory so your actual `~/.fuso/` data is never touched.
+
+```bash
+bundle exec rake test
+```
+
+### Project Structure
+
+```
+lib/fuso/
+├── app.rb           # Main Bubbletea model (Elm Architecture)
+├── config.rb        # Config loading & persistence
+├── session.rb       # Time entry recording & queries
+├── heartbeat.rb     # Suspend detection via heartbeat file
+├── styles.rb        # Lipgloss style definitions
+└── views/
+    ├── main_view.rb      # Timer screen (idle + tracking)
+    ├── settings_view.rb  # Project/category management
+    └── report_view.rb    # Weekly & monthly reports + CSV export
+```
+
+### Guidelines
+
+- Keep it minimal. Every feature should earn its screen space.
+- Follow the Elm Architecture pattern (`init` → `update` → `view`).
+- Add tests for new functionality.
+- No external services, no network calls, no accounts.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

data/exe/fuso

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fuso"
+
+if ARGV.empty?
+  # Launch TUI
+  Bubbletea.run(Fuso::App.new, alt_screen: true)
+elsif ARGV[0] == "report"
+  # CLI report mode
+  config = Fuso::Config.load
+  session = Fuso::Session.load
+  require "date"
+
+  case ARGV[1]
+  when "weekly"
+    date = Date.today
+    totals = session.weekly_breakdown(date)
+    monday = date - ((date.wday + 6) % 7)
+    sunday = monday + 6
+
+    puts "Fuso — Weekly Report"
+    puts "Week #{date.cweek}: #{monday.strftime('%b %d')} — #{sunday.strftime('%b %d, %Y')}"
+    puts ""
+    puts "#{'PROJECT / CATEGORY'.ljust(35)} #{'TOTAL'.rjust(8)}"
+    puts "─" * 45
+
+    grand_total = 0
+    totals.sort_by { |k, _| k }.each do |(project, category), seconds|
+      label = "#{project} / #{category}".ljust(35)
+      time = Fuso::Session.format_duration_hm(seconds).rjust(8)
+      puts "#{label} #{time}"
+      grand_total += seconds
+    end
+
+    puts "─" * 45
+    puts "#{'TOTAL'.ljust(35)} #{Fuso::Session.format_duration_hm(grand_total).rjust(8)}"
+  when "monthly"
+    date = Date.today
+    data = session.monthly_breakdown(date)
+    breakdown = data[:breakdown]
+    num_weeks = data[:num_weeks]
+
+    puts "Fuso — Monthly Report"
+    puts date.strftime("%B %Y")
+    puts ""
+
+    header = "PROJECT / CATEGORY".ljust(30)
+    (1..num_weeks).each { |w| header += "W#{w}".rjust(8) }
+    header += "TOTAL".rjust(10)
+    puts header
+    puts "─" * (30 + num_weeks * 8 + 10)
+
+    week_totals = Hash.new(0)
+    grand_total = 0
+
+    breakdown.sort_by { |k, _| k }.each do |(project, category), weeks|
+      label = "#{project} / #{category}"
+      label = label.length > 29 ? label[0..26] + "..." : label.ljust(30)
+      row = label
+
+      row_total = 0
+      (1..num_weeks).each do |w|
+        seconds = weeks[w]
+        row_total += seconds
+        week_totals[w] += seconds
+        time_str = seconds > 0 ? Fuso::Session.format_duration_hm(seconds) : "—"
+        row += time_str.rjust(8)
+      end
+
+      grand_total += row_total
+      row += Fuso::Session.format_duration_hm(row_total).rjust(10)
+      puts row
+    end
+
+    puts "─" * (30 + num_weeks * 8 + 10)
+    total_row = "TOTAL".ljust(30)
+    (1..num_weeks).each do |w|
+      seconds = week_totals[w]
+      time_str = seconds > 0 ? Fuso::Session.format_duration_hm(seconds) : "—"
+      total_row += time_str.rjust(8)
+    end
+    total_row += Fuso::Session.format_duration_hm(grand_total).rjust(10)
+    puts total_row
+  else
+    puts "Usage: fuso report [weekly|monthly]"
+  end
+else
+  puts "Usage: fuso [report weekly|monthly]"
+end