paradeiser 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 514aada5139d88a73f29e87af2fa9e05a83abcf5
-  data.tar.gz: bba7a583a6f59e396bf2b97b303a1298ed0d0558
+  metadata.gz: 4dcbd4bf94f9cbba76054b78656e283c3b626d32
+  data.tar.gz: 4368ba13bf80540e2a58bc76e49bb2347a1275e3
 SHA512:
-  metadata.gz: 3df87f14df263ac7abaa64e3a3919766e55b57d2859097d097cdf90d3b630ecf8126d03169ad897a46beb3fbd3b2555a76ee6c5d68c2bc5f5dffeb5781bb549c
-  data.tar.gz: 3c52d742719e3efae7ec2ccbf532a5503a40e071277ce8a51a52a056713362007bd68c0d2dfd7fdaa0b3844b4675bf9a93211410cf355d9240b178021793eea2
+  metadata.gz: 91a9cd45c540b4be0ee843f525329dd7f53287cfb0e8b746df60dae4ad1968a04077e7bae9a1249024d8eeab7b8cb718d25b29860e0efc29663810454d49c9fc
+  data.tar.gz: f72225528fedafccf789eb37a23daf9294803d0aa623e06da9a040844c049fd171a7efaf092382551833bfccbca79ae09450822a41f19469854bb9774b16a614

data/.gitignore

@@ -7,7 +7,6 @@ Gemfile.lock
 InstalledFiles
 _yardoc
 coverage
-doc/
 lib/bundler/man
 pkg
 rdoc
@@ -15,3 +14,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.cache_rake_t

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+bundler_args: --without development
+rvm:
+  - 2.0.0
+
+before_install:
+ - sudo apt-get update
+ - sudo apt-get install at

data/Gemfile

@@ -2,3 +2,9 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in paradeiser.gemspec
 gemspec
+
+group :test do
+  gem 'rake', '~> 10.0.0'
+  gem 'minitest', '~> 5.0.0'
+  gem 'fakefs', '~> 0.4.0', :require => "fakefs/safe"
+end

data/Guardfile

@@ -0,0 +1,17 @@
+guard 'bundler' do
+  watch('Gemfile')
+  watch(%r|^.*\.gemspec|)
+end
+
+guard 'minitest' do
+  watch(%r|^test/unit/test_(.*)\.rb|){|m| "test/unit/test_#{m[1]}.rb"}
+  watch(%r|^lib/*\.rb|){'test'}
+  watch(%r|^lib/.*/*\.rb|){'test'}
+  watch(%r{^lib/.*/([^/]+)\.rb$}){|m| "test/unit/test_#{m[1]}.rb"}
+  watch(%r|^test/helper\.rb|){'test'}
+  watch(%r{^lib/.*/views/(.*)/[^/]+\.erb$}){|m| "test/unit/test_#{m[1]}_view.rb"}
+
+  # Integration tests
+  watch(%r{^bin/([^/]+)$}){|m| "test/integration/test_#{m[1]}.rb"}
+  watch(%r|^test/integration/test_(.*)\.rb|){|m| "test/integration/test_#{m[1]}.rb"}
+end

data/README.md

@@ -1,15 +1,25 @@
 # Paradeiser
 
-  _Please note that this project is developed with the [readme-driven development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) method. As such, Paradeiser actually provides much less functionality than it is described here. Once a major milestone is reached, this README will be updated to reflect the actual status._
+[![Gem Version](https://badge.fury.io/rb/paradeiser.png)](http://badge.fury.io/rb/paradeiser)
+[![Build Status](https://secure.travis-ci.org/nerab/paradeiser.png?branch=master)](http://travis-ci.org/nerab/paradeiser)
 
-Paradeiser is a tool for the [Pomodoro Technique](http://www.pomodorotechnique.com/). It keeps track of the current pomodoro and assists the user in managing active and past pomodori:
+  _This project is developed with the [readme-driven development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) method. This file describes the functionality that is actually implemented, whereas the [VISION](VISION.md) describes the vision where the tool should go._
 
-* Records finished and cancelled pomodori as well as internal and external interruptions and other events
+Paradeiser is a command-line tool for the [Pomodoro Technique](http://www.pomodorotechnique.com/). It keeps track of the current pomodoro and assists the user in managing active and past pomodori:
+
+* Records finished pomodori
 * Keeps track of the timer for the active pomodoro and the break
-* Provides out-of-the-box reports that show details about finished and cancelled pomodori
-* Shows information about breaks and interruptions
+* Provides out-of-the-box reports
+
+Paradeiser itself is not concerned with the actual management of tasks. There are plenty of tools for that; e.g. [TaskWarrior](http://taskwarrior.org/).
+
+## Concepts
+
+### Rule #1
 
-Paradeiser itself is not concerned with the actual management of tasks. There are plenty of tools for that; the author prefers [TaskWarrior](http://taskwarrior.org/).
+  There must never be more than one pomodoro [xor](http://en.wikipedia.org/wiki/Xor) break at any given time.
+
+This is scoped to a single user account (not just the `$POM_DIR` directory, but also the `at` queue).
 
 ## Installation
 
@@ -21,220 +31,107 @@ Paradeiser itself is not concerned with the actual management of tasks. There ar
 
       $ pom start
 
-There can only be one active pomodoro or break at a time per user. Therefore, repeatedly calling start will have no effect (other than a warning message).
-
-If a break is still active, it will be stopped before the new pomodoro is started.
-
-Note that for a single user account (technically, for a `~/.paradeiser` directory), not more than one pomodoro [xor](http://en.wikipedia.org/wiki/Xor) one break can be active at any given time.
+Because of Rule #1, calling start while a pomodoro is active will print an error message.
 
 ### Finish the pomodoro
 
       $ pom finish
-      $ pom stop # alias
-
-If a pomodoro is active, it will be marked as successful after stopping it, regardless of whether the 25 minutes are over or not. If a break is active, it will be stopped. If neither a  pomodoro nor or break are active, a warning message will be printed.
-
-### Record an interruption of the current pomodoro
-
-      $ pom interrupt --external Phone call from boss
-      $ pom interrupt --internal "Couldn't stay away from Twitter"
-
-Remaining arguments, if present, will be added to the interrupt as annotation. If no pomodoro is active or interrupted (status is idle or paused), the command will throw an error.
-
-### Resume the pomodoro after an interruption
-
-      $ pom resume
-
-If there is no interrupted pomodoro, the command will throw an error.
 
-### Start a break
+If a pomodoro is active, it will be marked as successful after stopping it, regardless of whether the 25 minutes are over or not.
 
-      $ pom break [--short | --long]
+If there is no active pomodoro, an error message will be printed.
 
-If a pomodoro is active, it will be stopped. By default the break will be five minutes long. After four pomodori within a day, the break will be 30 minutes long. This can be overridden with `--short` or `--long`, with an optional argument value that determines the lenght of the break in minutes (e.g. `pom break --short=10`).
+### Initialize Paradeiser
 
-There is no public command to stop a break. Either a new pomodoro is started, which will implicitely stop the break, of the break ends naturally because it is over.
+* Initialize the default directory that is used to store the Paradeiser configuration and data:
 
-### Annotate a pomodoro
+          $ pom init
 
-      $ pom annotate This was intense, but I am happy about the work I finished.
+  Creates the `$POM_DIR` directory and the sample hooks in `$POM_DIR/hooks`. The data store will not be created on `pom init`, but when the first write operation happens (e.g. `pom start`, but not `pom report`).
 
-The annotation will be added to the active or, if none is active, to the most recently finished or cancelled pomodoro. Breaks cannot have annotations. If no text is given, the command throws an error.
+* Initialize an abritrary directory
 
-### Cancel the pomodoro
+          $ pom init /tmp
 
-      $ pom cancel Just couldn't concentrate anymore.
-      $ pom abandon # alias
+  This command initializes `/tmp` as `$POM_DIR`.
 
-It will be marked as unsuccessful (remember, a pomodoro is indivisible). If no pomodoro is active or interrupted (status is idle or paused), the command will throw an error. If a break is active, the command will do nothing except printing a warning. Remaining arguments, if present, will be added to the pomodoro as annotation.
+## Timer with `at`
 
-### Init Paradeiser
+A central aspect of the Pomodoro Technique is the timer function:
 
-      $ pom init
+  * The remaining time of the active pomodoro or break must be displayed to the user.
+  * When the pomodoro or break is over, the user also needs to get a notification.
 
-Creates the `~/.paradeiser` directory, an empty data store and the sample hooks in `~/.paradeiser/hooks`. If `~/.paradeiser` already exists, the command will fail with an error message.
+The `at` command is used for this. We just tell it to call
 
-### Location
+      pom finish
 
-  * List all locations
+when the pomodoro is over.
 
-        $ pom location
-        macbook@01:23:45:67:89:0A "Home Office"
-        macbook@45:01:89:0A:67:23 "Starbucks"
+When a pomodoro is started, Paradeiser enqueues itself to `at` like this:
 
-  * Show the label of a location
+      echo pom finish | at now + 25 minutes
 
-        $ pom location macbook@01:23:45:67:89:0A
-         Home Office
+When `at` calls Paradeiser with this command, the pomodoro / break will be over and Paradeiser can do all the internal processing related to stopping the pomodoro / break (incl. calling the appropriate hooks, see below).
 
-  * Show the identifier of a location
-
-        $ pom location "Home Office"
-        macbook@01:23:45:67:89:0A
-
-  * Label a location
-
-        $ pom location macbook@01:23:45:67:89:0A "Your Label"
-
-## Low-level commands
-
-We don't want another daemon, and `at` exists. We just tell `at` to call
-
-      pom _stop-break
-
-when the break is over. The underscore convention marks this command as a protected one that is not to be called from outside.
-
-So when `at` calls Paradeiser with this line, the pomodoro or break are over and Paradeiser does all the internal processing related to stopping the break (incl. calling the appropriate hooks, see below).
+Paradeiser uses a dedicated at queue named 'p' to organize its jobs and to prevent accidentially overwriting other scheduled tasks.
 
 ## Status
 
-      $ pom status # with an active pomodoro
-      Pomodoro #2 started at 11:03. 14 minutes remaining.
+Paradeiser can print the current status to STDOUT with the `pom status` command. The current state is provided as process exit status (which is also useful when the output is suppressed).
 
-      $ pom status # with no active pomodoro and a previously finished one
-      No pomodoro active. Last pomodoro was finished successfully at 2013-07-16 17.07.
+* Given an active pomodoro:
 
-      $ pom status # with no active pomodoro and a previously cancelled one
-      No pomodoro active. Last pomodoro was cancelled at 2013-07-16 17.07.
+          $ pom status
+          Pomodoro #2 is active (started 11:03, 14 minutes remaining).
 
-      $ pom status # with no active pomodoro and an active break
-      Taking a 5 minute break until 2013-07-16 17.07 (4 minutes remaining).
+          $ pom status > /dev/null
+          $ echo $?
+          0
 
-      $ pom status --short # short status (03:39 remaining in the active pomodoro or break)
-      03:39
+* Given no active pomodoro and the last one (not earlier as today) was finished:
 
-      $ pom status --format %C-%M:%S # custom status format, similar to date +%Y-%m-%dT%H:%M:%S
-      B03:39
+          $ pom status
+          No active pomodoro. Last one was finished at 16:58.
 
-      $ pom status --format JSON # output in JSON format
-      {
-        "status": {
-          "type": "break",
-          "length": 600,
-          "remaining": 363,
-          "start": 1373988295,
-          "end": 1373988595
-        }
-      }
+          $ pom status > /dev/null
+          $ echo $?
+          1
 
 ## Reports
 
       $ pom report
-      Daily Pomodoro Report for 2013-07-16
-
-      3 pomodori finished
-      1 pomodoro cancelled
-      1 internal interruptions (27 minutes in total)
-      2 external interruptions (2 hours and 28 minutes in total)
-      4 breaks (3 short, 1 long; 45 minutes in total)
-
-      Most efficient location: Home Office (2/0/1/0)
-      Least efficient location: Coffeshop (1/1/0/2)
-
-      The following locations do not have a label. Assign it with
-
-        $ pom location macbook@01:23:45:67:89:0A "Your Label"
-
-The command defaults to `--day`. Alternative options are `--week`, `--month` or `--year`. Without a value, the argument assumes the current day / week / month / year. The first day of the period can be specified as argument, e.g. `pom report --day=2013-07-18`. The period is parsed with [Chronic](http://chronic.rubyforge.org/), which also enables symbolic values like `pom report --month="last month"`.
-
-The efficiency is calculated (per location) from the number of successful vs. cancelled pomodori, together with the number and length of interruptions. Breaks are not counted towards efficiency.
-
-### Verbose Reports (timesheet)
-
-      $ pom report --verbose
-      TODO Ordered list of pomodori and breaks, each with annotations (like a time sheet)
-
-The same options as for regular reports apply.
-
-### Exporting a Report
-
-      $ pom report --weekly --format JSON # weekly report in JSON format
-      {
-        "TODO": "Specify"
-      }
-
-## Output Policy
-Paradeiser follows the [Rule of Silence](http://www.faqs.org/docs/artu/ch01s06.html#id2878450). If all goes well, a command will not print any output to `STDOUT`. Reports are exempted from this rule.
-
-Error and warning messages always go to `STDERR`.
+      <list of pomodori>
 
 ## Hooks
-Instead of handling tasks itself, Paradeiser integrates with external tools via hooks. Every event will attempt to find and execute an appropriate script in `~/.paradeiser/hooks/`. Sufficient information will be made available via environment variables.
+Instead of handling tasks itself, Paradeiser integrates with external tools via hooks. Every event will attempt to find and execute an appropriate script in `$POM_DIR/hooks/`. Sufficient information will be made available via environment variables.
 
-`pre-` hooks will be called before the action is executed internally. If a `pre-`hook exits non-zero, paradeiser will abort the action and exit non-zero itself; indicating in a message to STDERR which hook caused the abort.
+`before-` hooks will be called before the action is executed internally. If a `before-`hook exits non-zero, paradeiser will abort the action and exit non-zero itself; indicating in a message to STDERR which hook caused the abort.
 
-`post-` hooks will be called after the action was executed internally. The exit status of a `post`-hook will be passed through paradeiser, but it will not affect the execution of the action anymore.
+`after-` hooks will be called after the action was executed internally. The exit status of a `post`-hook will be passed through paradeiser, but it will not affect the execution of the action anymore.
 
 ### Available Hooks
 
-* `pre-start` is called after the `start` command was received, but before internal processing for the `start` action begins
-* `post-start` is called after all interal processing for the `start` action ended
-* `pre-finish` is called after the timer of the current pomodoro fired (the pomodoro is over), but before internal processing for the `finish` action begins
-* `post-finish` is called after all interal processing for the `finish` action ended
-* `pre-interrupt` is called after the `interrupt` command was received, but before internal action processing begins
-* `post-interrupt` is called after all interal processing for the `interrupt` action ended
-* `pre-cancel` is called after the `cancel` command was received, but before internal action processing begins
-* `post-cancel` is called after all interal processing for the `cancel` action ended
-* `pre-break` is called after the `break` command was received, but before internal processing for the `break` action begins
-* `post-break` is called after the timer of the current break fired (the break is over), but after internal processing for the `break` action ended
-
-Commands are invoked by the user (e.g. `pom start`). Actions are what Paradeiser does internally.
+* `before-start` is called after the `start` command was received, but before internal processing for the `start` action begins
+* `after-start` is called after all interal processing for the `start` action ended
+* `before-finish` is called after the timer of the current pomodoro fired (the pomodoro is over), but before internal processing for the `finish` action begins
+* `after-finish` is called after all interal processing for the `finish` action ended
 
 Examples for the use of hooks are:
 
-* Displaying a desktop notification on `pre-finish`
-* tmux status bar integration like [pomo](https://github.com/visionmedia/pomo) by writing the status to `~/.pomo_stat` from the `post-` hooks.
-* Displaying a desktop notification on Linux:
-
-        # ~/.paradeiser/hooks/post-stop
-        notify-send "Break" "$POMODORO_TITLE is over." -u critical
-
-* Displaying a desktop notification on MacOS:
-
-        # ~/.paradeiser/hooks/post-stop
-        terminal-notifier-success  -message "$POMODORO_TITLE is over."
-
-`$POMODORO_TITLE` is one of the environment variables set by Paradeiser that provides the context for hooks. See below for the full list of available environment variables.
+* Displaying a desktop notification on `after-finish`
+* tmux status bar integration like [pomo](https://github.com/visionmedia/pomo) by writing the status to `~/.pomo_stat` from the `after-` hooks.
+* Displaying a desktop notification
 
-### Edit a hook
+`$POM_TITLE` is one of the environment variables set by Paradeiser that provides the context for hooks. See below for the full list of available environment variables.
 
-      $ pom edit post-stop
+## Environment Variables
 
-Launches `$VISUAL` (or, if empty, `$EDITOR`) with the given hook.
-
-## Taskwarrior Integration
-
-This is deployed to `~/.paradeiser/hooks/post-finish` by default.
-
-      # exit unless $(task)
-
-      # find all active
-      active = $(task active) # doesn't work yet; find the right column with 'task columns' and the info in http://taskwarrior.org/projects/taskwarrior/wiki/Feature_custom_reports
-
-      # TODO tag all active tasks so that we can re-start them
-
-      # stop all active
-      task $(task active) stop
+Variable | Used in | Description
+--- | --- | ---
+`$POM_DIR` | Everywhere | Directory where the data store and the hooks are stored. Defaults to `~/.paradeiser/`.
+`$POM_ID` | Hooks | Identifier of the pomodoro
+`$POM_STARTED_AT` | Hooks | Timestamp of when the pomodoro was started
 
 ## Similar Projects
 
@@ -250,11 +147,14 @@ They have a lot of what I wanted, but pomo focuses very much on the tasks themse
 ### State Machine
 Paradeiser uses a [state machine](https://github.com/pluginaweek/state_machine) to model a pomodoro. Internal event handlers do the actual work; among them is the task of calling the external hooks.
 
-### I18N
-Paradeiser uses [I18N](https://github.com/svenfuchs/i18n) to translate messages and localize time and date formats.
+![State Transition Diagram](https://rawgithub.com/nerab/paradeiser/master/doc/Paradeiser::Pomodoro_status.svg)
+
+The graph was created using the rake task that comes with `state_machine`:
+
+    rake state_machine:draw CLASS=Paradeiser::Pomodoro TARGET=doc FORMAT=svg HUMAN_NAMES=true ORIENTATION=landscape
 
 ## API
-The actual storage backend is *not a public API* and may change at any given time. External tools should use the Ruby API instead, or rely on the JSON export.
+The actual storage backend is *not a public API* and may change at any given time.
 
 ## Sync
 In todays world of distributed devices, synching data is a problem almost every app needs to solve. Paradeiser is no exception - it is very easy to come up with use cases that involve many computers. Maybe the user has different devices (mobile and desktop), maybe the user works in different environments, and wants to record all pomodori into a single system.
@@ -268,20 +168,9 @@ There are many potential solutions to this problem:
 
 All of these are too much overhead right now, so the decision was made to keep Paradeiser simple and not implement any sync features. This may me revisited in a later version of the app.
 
-## Location
-Recording the location of a pomodoro allows Paradeiser to compare the average count of successful and cancelled pomodori and the number of interruptions by location, so that a report can tell in which environment we get the most work done.
-
-In order to record the current location at the start of the pomodoro, Paradeiser will record the hostname and the MAC address of the default gateway:
-
-* OSX
-
-        arp 0.0.0.0 | head -1 | awk {'print $4'}
-
-* Linux:
-
-        GATEWAY=$(netstat -rn | grep "^0.0.0.0" | cut -c17-31); ping -c1 $GATEWAY >/dev/null; arp -n $GATEWAY | tail -n1 | cut -c34-50
+## Issues
 
-The location is then used to assign a label to one or more hostname@MAC strings, which will be used in a report.
+1. `at` is disabled on MacOS by default. You will need to [turn it on](https://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man8/atrun.8.html) in order to make Paradeiser work correctly.
 
 ## What about the app's name?
 In Austrian German, "Paradeiser" means tomato, of which the Italian translation is pomodoro.

data/Rakefile

@@ -1 +1,12 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+require 'paradeiser'
+require 'tasks/state_machine'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test' << 'test/helpers'
+  test.test_files = FileList['test/**/test_*.rb']
+end
+
+task :default => :test

data/TODO.md

@@ -0,0 +1,62 @@
+# Paradeiser Backlog
+
+* Implement break
+
+  Cancel all enqueued commands on `pom break`, just like with `pom start`. Otherwise commands already enqueued to `at` would accidentially change a newer thing while thinking of operating on the older thing.
+
+  This is safe (and required) because of Rule #1.
+
+* Implement interrupts
+
+* Implement `pom annotate` and annotations for most commands
+
+* Improve status messages with relative times and dates (`distance_of_time_in_words_to_now`)
+
+* POM_ID is not available to `*-start` hooks because the pomodoro wasn't saved yet. We could either assign it before saving it or allow saving idle pomodori.
+
+* A text-based repo format would be much more UNIX-like. Think about a JSON repo. Loading it could share a lot of code with import (which we will need anyway). And we cannot trust a JSON repo any more than an import file.
+
+* Make `start` the default subcommand for `pom break`, so that `pom break` is the same as `pom break start`.
+
+* Have the router catch warnings (those errors that extend Warning) and print the message to STDERR, but do not exit. The actual exit code is still determined by the controller.
+
+* Add more tests for the scheduler (error cases like no access, or job not added due to other issues)
+
+* With the --trace option, print the job id and instructions to look at the `at` queue after enqueing a job. Also, print if a hook wasn't found or was found, but is not executable.
+
+* Scope the id to the day by introducing a key class the is an aggregate of day and id.
+  - The view only shows the id for any given day in most reports. That means that a day (current by default, others in queries or import) is the scope of a pomodoro id.
+  - We don't have to globally identify pomodori with uuids because of rule #1
+
+  This also makes `pom import` simple - only if there is nothing on record for the time between the start and end times of the imported thing, it is accepted into our system.
+
+  Deleting or overwriting existing pomodori is not supported. Manual editing, if ever needed, can be done with exporting, deleting the db file, fixing up the exported file, and importing it into a fresh $POM_DIR.
+
+  Active pomodori or breaks are not exported or imported.
+
+* Use Highline#color to color output pro:Paradeiser
+  - Status: red/green/yellow
+  - Errors red, warnings yellow, otherwise white
+  - Turn off when running w/o tty and when --no-color is given
+
+* Print only the id of the pom that was just created / modified / queried when not running in a tty
+  - test with `if $stdin.tty?`
+  - If that approach works well, suggest it for TaskWarrior too (for bulk actions, e.g. in scripts)
+
+* Implement documentation Approach
+  - `pom help` is what the user will use to get information.
+  - Not sure how to allow the user to look at features that are not related to a command. Either extend `pom help` to accept arbitrary keywords, or look into 'gem man`.
+
+  Development Tasks
+
+  - Describe each feature / command in one md file (alternatively, store at GitHub issues as feature, would allow discussion).
+  - When a feature is done, move it to a doc file (not the readme; it's getting too big) or a wiki page.
+  - `pom help <command>` consumes the feature files.
+  - Feature files could be exported onto a the github wiki or static pages about Paradeiser.
+  - As part of finishing a feature, the feature file is moved from the backlog file to in individual doc file, and the README is updated to mention that feature.
+
+* Promote Paradeiser
+  - Publish an [ASCII cast](http://ascii.io/)
+  - Tell the TaskWarrior community about Paradeiser
+  - Tell the Pomodoro community about Paradeiser
+  - Tell the Ruby community about Paradeiser (e.g. @neverbendeasy does kanban)