timet 0.9.2 → 1.0.0

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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 07b78b25d014cabc13d5c2b80b0a1736d695d20397480c9d7d35ee739631add2
4
- data.tar.gz: e25a3dc925ae01dc5902d7e1e72c57a46052f525e3a7010db2592a167050eb6f
3
+ metadata.gz: 2f05df826f56c4161b878136fed6db433c86f717d1853dadc5b0255f98c5197e
4
+ data.tar.gz: 44699896bbfcc7b49409f4cb2bece028b4719ef9b1e97f7d83221ea1073e863f
5
5
  SHA512:
6
- metadata.gz: cb13897099a5427c0174483d75841eee0a7b3b3d95b49e28ba8b3e169ddfaf208bbe80c2ea811b33460d5d5342e7a8bcc435aa72dc47059816a7b8452cbc2713
7
- data.tar.gz: fd44ee706b65ae6cfe3802641dc885ae10128a43c4d4be97738474e8e0378749bd669940a6ce28bcc36a24d8ea2a4c63f0ece654eb27a93f1fbe09f980f4f781
6
+ metadata.gz: 4af0f240762026b43a3e4c9f3833d81e51729c0ea6916537be9a9893e40d602e7f7fab49d2d552a6ee736f3efd3e8c7ea6f8ad2ff01f2306c97a0e6568b354ef
7
+ data.tar.gz: d368ea5f22cabd607a30056cbca07b4bc80501775a1bea9094d7c842a8277f3d2656fe334a6a038b2671475b9278c00ea7eb9adec15190e1f35e5f1dec44f142
data/README.md CHANGED
@@ -20,147 +20,160 @@ In addition, if possible, export your time tracking data to CSV for analysis and
20
20
 
21
21
  ## Requirements
22
22
 
23
- * Ruby version: >= 3.0.0
24
- * sqlite3: > 1.7
25
-
23
+ - Ruby version: >= 3.0.0
24
+ - sqlite3: > 1.7
26
25
 
27
26
  Old versions of Ruby and Sqlite:
28
27
 
29
- * [Ruby >= 2.7](https://github.com/frankvielma/timet/tree/ruby-2.7.0)
30
-
31
- * [Ruby >= 2.4](https://github.com/frankvielma/timet/tree/ruby-2.4.0)
32
-
28
+ - [Ruby >= 2.7](https://github.com/frankvielma/timet/tree/ruby-2.7.0)
33
29
 
30
+ - [Ruby >= 2.4](https://github.com/frankvielma/timet/tree/ruby-2.4.0)
34
31
 
35
32
  ## Installation
36
33
 
37
34
  Install the gem by executing:
35
+
38
36
  ```bash
39
37
  gem install timet
40
38
  ```
41
39
 
42
40
  ## Usage
43
41
 
44
- - **timet start [tag] --notes='...'**: Starts tracking time for a task labeled with the provided [tag] and notes (optional). Example:
45
- ```bash
46
- timet start task1 --notes='Meeting with client'
47
-
48
- or
49
-
50
- timet start task1 'Meeting with client'
51
- ```
52
-
53
- ```
54
- Tracked time report [today]:
55
- +-------+------------+--------+----------+----------+----------+--------------------------+
56
- | Id | Date | Tag | Start | End | Duration | Notes |
57
- +-------+------------+--------+----------+----------+----------+--------------------------+
58
- | 1 | 2024-08-09 | task1 | 14:55:07 | - | 00:00:00 | Meeting with client |
59
- +-------+------------+--------+----------+----------+----------+--------------------------+
60
- | Total: | 00:00:00 | |
61
- +-------+------------+--------+----------+----------+----------+--------------------------+
62
- ```
42
+ - timet start [tag] --notes="" --pomodoro=[minutes]**: Starts tracking time for a task labeled with the provided [tag], notes and "pomodoro time" in minutes (optional). Example:
43
+
44
+ ```bash
45
+ timet start task1 --notes="Meeting with client" --pomodoro=25
46
+
47
+ or
48
+
49
+ timet start task1 "Meeting with client" 25
50
+ ```
51
+
52
+ ```
53
+ Tracked time report [today]:
54
+ +-------+------------+--------+----------+----------+----------+--------------------------+
55
+ | Id | Date | Tag | Start | End | Duration | Notes |
56
+ +-------+------------+--------+----------+----------+----------+--------------------------+
57
+ | 1 | 2024-08-09 | task1 | 14:55:07 | - | 00:00:00 | Meeting with client |
58
+ +-------+------------+--------+----------+----------+----------+--------------------------+
59
+ | Total: | 00:00:00 | |
60
+ +-------+------------+--------+----------+----------+----------+--------------------------+
61
+ ```
62
+
63
+ This command will initiate a 25-minute Pomodoro session for the task "task1" with the provided description.
64
+
65
+ ### Pomodoro Integration
66
+
67
+ The `pomodoro` option in the `start` command enhances time tracking by integrating the Pomodoro Technique. Users can specify a Pomodoro session length in minutes, like `pomodoro=25`, to start a 25-minute work interval. The app automatically tracks time and notifies users when the interval ends, helping maintain focus.
68
+
69
+ **Benefits**
70
+
71
+ - **Flexibility**: Supports various productivity strategies.
72
+ - **Focus**: Encourages disciplined work practices.
73
+ - **Productivity**: Helps achieve higher productivity and better time management.
74
+
75
+ ---
63
76
 
64
77
  - **timet stop**: Stops tracking the current task, records the elapsed time, and displays the total time spent on all tasks.
65
78
 
66
- ```bash
67
- timet stop
68
- ```
69
-
70
- ```
71
- Tracked time report [today]:
72
- +-------+------------+--------+----------+----------+----------+--------------------------+
73
- | Id | Date | Tag | Start | End | Duration | Notes |
74
- +-------+------------+--------+----------+----------+----------+--------------------------+
75
- | 1 | 2024-08-09 | task1 | 14:55:07 | 15:55:07 | 01:00:00 | Meeting with client |
76
- +-------+------------+--------+----------+----------+----------+--------------------------+
77
- | Total: | 01:00:00 | |
78
- +-------+------------+--------+----------+----------+----------+--------------------------+
79
- ```
79
+ ```bash
80
+ timet stop
81
+ ```
80
82
 
83
+ ```
84
+ Tracked time report [today]:
85
+ +-------+------------+--------+----------+----------+----------+--------------------------+
86
+ | Id | Date | Tag | Start | End | Duration | Notes |
87
+ +-------+------------+--------+----------+----------+----------+--------------------------+
88
+ | 1 | 2024-08-09 | task1 | 14:55:07 | 15:55:07 | 01:00:00 | Meeting with client |
89
+ +-------+------------+--------+----------+----------+----------+--------------------------+
90
+ | Total: | 01:00:00 | |
91
+ +-------+------------+--------+----------+----------+----------+--------------------------+
92
+ ```
93
+ ---
81
94
  - **timet resume**: It allows users to quickly resume tracking a task that was previously in progress.
82
- ```
83
- Tracked time report [today]:
84
- +-------+------------+--------+----------+----------+----------+--------------------------+
85
- | Id | Date | Tag | Start | End | Duration | Notes |
86
- +-------+------------+--------+----------+----------+----------+--------------------------+
87
- | 2 | 2024-08-09 | task1 | 16:15:07 | - | 00:00:00 | Meeting with client |
88
- | 1 | | task1 | 14:55:07 | 15:55:07 | 01:00:00 | Meeting with client |
89
- +-------+------------+--------+----------+----------+----------+--------------------------+
90
- | Total: | 01:00:00 | |
91
- +-------+------------+--------+----------+----------+----------+--------------------------+
92
- ```
93
-
94
95
 
96
+ ```
97
+ Tracked time report [today]:
98
+ +-------+------------+--------+----------+----------+----------+--------------------------+
99
+ | Id | Date | Tag | Start | End | Duration | Notes |
100
+ +-------+------------+--------+----------+----------+----------+--------------------------+
101
+ | 2 | 2024-08-09 | task1 | 16:15:07 | - | 00:00:00 | Meeting with client |
102
+ | 1 | | task1 | 14:55:07 | 15:55:07 | 01:00:00 | Meeting with client |
103
+ +-------+------------+--------+----------+----------+----------+--------------------------+
104
+ | Total: | 01:00:00 | |
105
+ +-------+------------+--------+----------+----------+----------+--------------------------+
106
+ ```
107
+ ---
95
108
  - **timet edit**: It allows users to update a task's notes, tag, start, or end fields. Users can either interactively select the field and provide a new value or specify them directly in the command.
96
109
 
97
110
  - **Interactive Mode:**
98
- ```bash
99
- timet e 1
100
- ```
101
-
102
- ```
103
- Tracked time report [today]:
104
- +-------+------------+--------+----------+----------+----------+--------------------------+
105
- | Id | Date | Tag | Start | End | Duration | Notes |
106
- +-------+------------+--------+----------+----------+----------+--------------------------+
107
- | 2 | 2024-08-09 | task1 | 16:15:07 | - | 00:00:00 | Meeting with client |
108
- | 1 | | task1 | 14:55:07 | 15:55:07 | 01:00:00 | Meeting with client |
109
- +-------+------------+--------+----------+----------+----------+--------------------------+
110
- | Total: | 01:00:00 | |
111
- +-------+------------+--------+----------+----------+----------+--------------------------+
112
- Edit Field? (Press ↑/↓ arrow to move and Enter to select)
113
- ‣ Notes
114
- Tag
115
- Start
116
- End
117
- ```
118
111
 
112
+ ```bash
113
+ timet e 1
114
+ ```
119
115
 
120
- - **Direct Specification Mode:**
121
- ```bash
122
- timet e 1 notes "New Meeting Notes"
123
- ```
116
+ ```
117
+ Tracked time report [today]:
118
+ +-------+------------+--------+----------+----------+----------+--------------------------+
119
+ | Id | Date | Tag | Start | End | Duration | Notes |
120
+ +-------+------------+--------+----------+----------+----------+--------------------------+
121
+ | 2 | 2024-08-09 | task1 | 16:15:07 | - | 00:00:00 | Meeting with client |
122
+ | 1 | | task1 | 14:55:07 | 15:55:07 | 01:00:00 | Meeting with client |
123
+ +-------+------------+--------+----------+----------+----------+--------------------------+
124
+ | Total: | 01:00:00 | |
125
+ +-------+------------+--------+----------+----------+----------+--------------------------+
126
+ Edit Field? (Press ↑/↓ arrow to move and Enter to select)
127
+ ‣ Notes
128
+ Tag
129
+ Start
130
+ End
131
+ ```
124
132
 
125
- ```
126
- Tracked time report [today]:
127
- +-------+------------+--------+----------+----------+----------+--------------------------+
128
- | Id | Date | Tag | Start | End | Duration | Notes |
129
- +-------+------------+--------+----------+----------+----------+--------------------------+
130
- | 2 | 2024-08-09 | task1 | 16:15:07 | - | 00:00:00 | Meeting with client |
131
- | 1 | | task1 | 14:55:07 | 15:55:07 | 01:00:00 | New Meeting Note |
132
- +-------+------------+--------+----------+----------+----------+--------------------------+
133
- | Total: | 01:00:00 | |
134
- +-------+------------+--------+----------+----------+----------+--------------------------+
135
- ```
133
+ - **Direct Specification Mode:**
136
134
 
135
+ ```bash
136
+ timet e 1 notes "New Meeting Notes"
137
+ ```
137
138
 
139
+ ```
140
+ Tracked time report [today]:
141
+ +-------+------------+--------+----------+----------+----------+--------------------------+
142
+ | Id | Date | Tag | Start | End | Duration | Notes |
143
+ +-------+------------+--------+----------+----------+----------+--------------------------+
144
+ | 2 | 2024-08-09 | task1 | 16:15:07 | - | 00:00:00 | Meeting with client |
145
+ | 1 | | task1 | 14:55:07 | 15:55:07 | 01:00:00 | New Meeting Note |
146
+ +-------+------------+--------+----------+----------+----------+--------------------------+
147
+ | Total: | 01:00:00 | |
148
+ +-------+------------+--------+----------+----------+----------+--------------------------+
149
+ ```
138
150
 
139
151
  ## Command Reference
140
152
 
141
- | Command | Description | Example Usage |
142
- |----------------------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------|
143
- | `timet start [tag] --notes='...'` | Start tracking time for a task labeled [tag] and notes (optional). | `timet start Task "My notes"` |
144
- | `timet stop` | Stop tracking time. | `timet start Task "My notes"` |
145
- | `timet summary today (t)` | Display a report of tracked time for today. | `timet su t` or `timet su` |
146
- | `timet summary yesterday (y)` | Display a report of tracked time for yesterday. | `timet su y` |
147
- | `timet summary week (w)` | Display a report of tracked time for the week. | `timet su w` |
148
- | `timet summary month (m)` | Resume tracking the last month. | `timet su m` |
149
- | `timet su t --csv=[filename]` | Display a report of tracked time for today and export it to `filename.csv`. | `timet su t --csv=file.csv` |
150
- | `timet summary resume (r)` | Resume tracking the last task. | `timet su r` |
151
- | `timet delete [id]` | Delete a task by its ID. | `timet d [id]` |
152
- | `timet cancel` | Cancel active time tracking. | `timet c` |
153
- | `timet edit [id]` | Update a task's notes, tag, start or end fields. | `timet e [1]` |
154
- | `timet su [date]` | Display a report of tracked time for a specific date. | `timet su 2024-01-03` |
155
- | `timet su [start_date]..[end_date]` | Display a report of tracked time for a date range. | `timet su 2024-01-02..2024-01-03` |
156
-
153
+ | Command | Description | Example Usage |
154
+ | ----------------------------------- | --------------------------------------------------------------------------- | --------------------------------- |
155
+ | `timet start [tag] --notes='' --pomodoro=[time]` | Start tracking time for a task labeled [tag] and notes (optional). | `timet start Task "My notes" 25` |
156
+ | `timet stop` | Stop tracking time. | `timet start Task "My notes"` |
157
+ | `timet summary today (t)` | Display a report of tracked time for today. | `timet su t` or `timet su` |
158
+ | `timet summary yesterday (y)` | Display a report of tracked time for yesterday. | `timet su y` |
159
+ | `timet summary week (w)` | Display a report of tracked time for the week. | `timet su w` |
160
+ | `timet summary month (m)` | Resume tracking the last month. | `timet su m` |
161
+ | `timet su t --csv=[filename]` | Display a report of tracked time for today and export it to `filename.csv`. | `timet su t --csv=file.csv` |
162
+ | `timet summary resume (r)` | Resume tracking the last task. | `timet su r` |
163
+ | `timet delete [id]` | Delete a task by its ID. | `timet d [id]` |
164
+ | `timet cancel` | Cancel active time tracking. | `timet c` |
165
+ | `timet edit [id]` | Update a task's notes, tag, start or end fields. | `timet e [1]` |
166
+ | `timet su [date]` | Display a report of tracked time for a specific date. | `timet su 2024-01-03` |
167
+ | `timet su [start_date]..[end_date]` | Display a report of tracked time for a date range. | `timet su 2024-01-02..2024-01-03` |
157
168
 
158
169
  ### Date Range in Summary
159
170
 
160
171
  The `timet summary` command now supports specifying a date range for generating reports. This allows users to filter and summarize data within specific date intervals. The date format is in ISO 8601 format (YYYY-MM-DD).
161
172
 
162
173
  #### Examples:
174
+
163
175
  - **Single Date**: Display a report for a specific date.
176
+
164
177
  ```sh
165
178
  timet su 2024-01-03
166
179
  ```
@@ -170,10 +183,9 @@ The `timet summary` command now supports specifying a date range for generating
170
183
  timet su 2024-01-02..2024-01-03
171
184
  ```
172
185
 
173
-
174
186
  ## Data
175
- Timet's data is stored in ~/.timet.db
176
187
 
188
+ Timet's data is stored in ~/.timet.db
177
189
 
178
190
  ## Development
179
191
 
@@ -185,6 +197,14 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
185
197
 
186
198
  Bug reports and pull requests are welcome on GitHub at https://github.com/frankvielma/timet. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/frankvielma/timet/blob/master/CODE_OF_CONDUCT.md).
187
199
 
200
+ ## Buy Me A Coffee! ☕
201
+
202
+ Many people have contacted me asking how to contribute. Any contribution, from a virtual coffee to a kind word, is greatly appreciated and helps me continue my work. Please only donate if you're able, as there are no refunds. Your support is entirely voluntary, and I thank you for your consideration.
203
+
204
+ ![Buy me a coffee!](btc.png)
205
+
206
+ bc1qkg9me2jsuhpzu2hp9kkpxagwtf9ewnyfl4kszl
207
+
188
208
  ## License
189
209
 
190
210
  The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
data/btc.png ADDED
Binary file
@@ -37,26 +37,37 @@ module Timet
37
37
 
38
38
  desc "start [tag] --notes='[notes]'", 'Start time tracking for a specific tag with optional notes'
39
39
  option :notes, type: :string, desc: 'Add a note'
40
+ option :pomodoro, type: :numeric, desc: 'Pomodoro time in minutes'
40
41
  # Starts a new tracking session with the given tag and optional notes.
41
42
  #
43
+ # This method initializes a new tracking session by inserting a new item into the database
44
+ # with the provided tag and optional notes. If a Pomodoro time is specified, it will also
45
+ # trigger a sound and notification after the specified time has elapsed.
46
+ #
42
47
  # @param tag [String] The tag associated with the tracking session. This is a required parameter.
43
48
  # @param notes [String, nil] Optional notes to be associated with the tracking session. If not provided, it defaults to the value in `options[:notes]`.
49
+ # @param pomodoro [Numeric, nil] Optional Pomodoro time in minutes. If not provided, it defaults to the value in `options[:pomodoro]`.
44
50
  #
45
- # @return [void] This method does not return a value; it performs side effects such as inserting a tracking item and generating a summary.
51
+ # @return [void] This method does not return a value; it performs side effects such as inserting a tracking item, playing a sound, sending a notification, and generating a summary.
46
52
  #
47
53
  # @example Start a tracking session with a tag and notes
48
- # start('work', 'Starting work on project X')
54
+ # start('work', 'Starting work on project X', 25)
49
55
  #
50
56
  # @example Start a tracking session with only a tag
51
57
  # start('break')
52
58
  #
53
59
  # @note The method uses `TimeHelper.current_timestamp` to get the current timestamp for the start time.
60
+ # @note The method calls `play_sound_and_notify` if a Pomodoro time is provided.
54
61
  # @note The method calls `summary` to generate a summary after inserting the tracking item.
55
- def start(tag, notes = nil)
62
+ def start(tag, notes = nil, pomodoro = nil)
56
63
  start_time = TimeHelper.current_timestamp
57
64
  notes = options[:notes] || notes
65
+ pomodoro = (options[:pomodoro] || pomodoro).to_i
58
66
 
59
- @db.insert_item(start_time, tag, notes) if VALID_STATUSES_FOR_INSERTION.include?(@db.last_item_status)
67
+ if VALID_STATUSES_FOR_INSERTION.include?(@db.last_item_status)
68
+ @db.insert_item(start_time, tag, notes)
69
+ play_sound_and_notify(pomodoro * 60, tag) if pomodoro > 0
70
+ end
60
71
  summary
61
72
  end
62
73
 
@@ -71,16 +82,13 @@ module Timet
71
82
  # @note The method checks if the last tracking item is in progress by calling `@db.last_item_status`.
72
83
  # @note If the last item is in progress, it fetches the last item's ID using `@db.fetch_last_id` and updates it with the current timestamp.
73
84
  # @note The method then fetches the last item using `@db.last_item` and generates a summary if the result is not nil.
74
- def stop
75
- if @db.last_item_status == :in_progress
76
- last_id = @db.fetch_last_id
77
- @db.update_item(last_id, 'end', TimeHelper.current_timestamp)
78
- end
79
- result = @db.last_item
85
+ def stop(display = nil)
86
+ return unless @db.last_item_status == :in_progress
80
87
 
81
- return unless result
88
+ last_id = @db.fetch_last_id
89
+ @db.update_item(last_id, 'end', TimeHelper.current_timestamp)
82
90
 
83
- summary
91
+ summary unless display
84
92
  end
85
93
 
86
94
  desc 'resume (r)', 'resume last task'
@@ -68,5 +68,36 @@ module Timet
68
68
 
69
69
  value
70
70
  end
71
+
72
+ # Plays a sound and sends a notification after a specified time.
73
+ #
74
+ # This method is designed to work on Linux and macOS. It triggers a sound and a notification
75
+ # after the specified time has elapsed. On Linux, it also stops a Pomodoro session and sends
76
+ # a desktop notification. On macOS, it plays a system sound and displays a notification.
77
+ #
78
+ # @param time [Integer] The duration in seconds to wait before playing the sound and sending the notification.
79
+ # @param tag [String] The tag associated with the Pomodoro session.
80
+ #
81
+ # @example
82
+ # play_sound_and_notify(1500, 'work')
83
+ #
84
+ # @note This method uses platform-specific commands and assumes the presence of certain utilities
85
+ # (e.g., `notify-send` on Linux, `afplay` on macOS). Ensure these utilities are available
86
+ # on the respective operating systems.
87
+ #
88
+ # @raise [RuntimeError] If the operating system is not supported.
89
+ #
90
+ # @return [void]
91
+ def play_sound_and_notify(time, tag)
92
+ if RUBY_PLATFORM.downcase.include?('linux')
93
+ pid = spawn("sleep #{time} && tput bel && /home/frank/Software/frankvielma/gems/timet/bin/timet stop 0 && notify-send --icon=clock 'Pomodoro session complete! (tag: #{tag}) Time for a break.' &")
94
+ Process.wait(pid)
95
+ elsif RUBY_PLATFORM.downcase.include?('darwin')
96
+ pid = spawn("(sleep #{time} && afplay /System/Library/Sounds/Basso.aiff && osascript -e 'display notification \"Pomodoro session complete! Time for a break.\"') &")
97
+ Process.wait(pid)
98
+ else
99
+ puts 'Unsupported operating system'
100
+ end
101
+ end
71
102
  end
72
103
  end
data/lib/timet/version.rb CHANGED
@@ -6,6 +6,6 @@ module Timet
6
6
  # @return [String] The version number in the format 'major.minor.patch'.
7
7
  #
8
8
  # @example Get the version of the Timet application
9
- # Timet::VERSION # => '0.9.1'
10
- VERSION = '0.9.2'
9
+ # Timet::VERSION # => '1.0.0'
10
+ VERSION = '1.0.0'
11
11
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: timet
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.9.2
4
+ version: 1.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Frank Vielma
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2024-10-06 00:00:00.000000000 Z
11
+ date: 2024-10-07 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: thor
@@ -75,6 +75,7 @@ files:
75
75
  - README.md
76
76
  - Rakefile
77
77
  - bin/timet
78
+ - btc.png
78
79
  - lib/timet.rb
79
80
  - lib/timet/application.rb
80
81
  - lib/timet/application_helper.rb