timcharper / Caprese

h1. Caprese

"Caprese":http://github.com/timcharper/caprese (pronounced ca-PRAY-zay) is a helper app for the "Mac OS X Pomodoro App":http://pomodoro.ugolandini.com/Mac by Ugo Landini. It provides an easy-to-configure suite of actions that can be executed and unexecuted when your Pomodoro starts and stops. Actions include:

• Set iChat status for all accounts
• Set adium status for all accounts
• Set skype status
• Announce pomodoro status to campfire
• Launch applications, hiding all other windows
• Quit applications
• Block applications
• Block domains (blocks by IP using the Mac OS X firewall)

h2. Installation

h3. Prerequisites

• A Ruby interpreter, 1.8.6 or greater
• XCode Mac developer tools (required to install Ruby/AppleScript interop support)

h3. Step 1: Download and install caprese

Caprese requires root access and should be installed in /opt/caprese, owned as root.

Option 1: download a release file from github (see http://github.com/timcharper/caprese/downloads), and unzip it to /opt/caprese. If the folder /opt/caprese/lib exists, you've done it right.

Option 2: clone the git repository and run edge. updates are as easy a 'git pull'.

  sudo su -
  # type password
  cd /opt
  git clone git://github.com/timcharper/caprese.git

If you prefer not to run caprese with root privileges, many features are still available without it. Install caprese to any folder and skip the "sudo access section". Domain blocking and application blocking are likely not work.

h3. Step 2: grant password free sudo access to /opt/caprese/caprese

Make it so you can run sudo /opt/caprese/caprese without supplying a password. I can't guarantee that this will be 100% safe to do, but if you make sure that only root has access to write or create any file in /opt/caprese, I don't foresee any security threat.

Edit your sudoers file by running visudo as root, and put these lines at the bottom of the file:

  %admin  ALL=PASSWD: ALL, NOPASSWD: /opt/caprese/caprese

(hint: copy above line, then in visudo, press shift-G, o, command-v, , :wq)

h3. Step 3: Gem dependencies

Use sudo geminstaller to make sure you have the needed gems. Also, you will want to make sure that you are using your System-supplied version of ruby, and not your custom built version, as Mac OS X will likely ignore your path settings and pick the System-supplied.

I recommend:

  cd path_to_caprese
  sudo /usr/bin/gem install geminstaller
  sudo /usr/bin/geminstaller

h3. Step 4: Configure

copy /opt/caprese/config.rb.sample to /opt/caprese/config.rb, and then edit it with your favorite text editor. The config file should be self-explanatory.

h3. Step 5: Test

As your user (NOT ROOT!), run:

  sudo -k

This clears sudo timestamp so sudo will begin prompting for a password again.

  sudo /opt/caprese/caprese start DESCRIPTION="test description"

You should have seen no password prompt. If you did, something went wrong in Step 2. To diagnose:

• Check to make sure your user is apart of the admin group
• make sure no other config lines conflict.

If you saw a configuration error, follow the instructions shown. If it was a ruby parse error, you probably forgot to close a parenthesis pair, forgot a command, put in an extra command, etc.

  sudo /opt/caprese/caprese stop

This command should have undid everything the start command did

  sudo ls -l /root

This should've prompted you for a password. If it doesn't, your sudoers change was to permissive, or you'd given free rain to 'ls' previously.

h3. Step 6: Integrating with Pomodoro.app

Go to the config -> applescript.

Check the checkboxes next to "start", "reset", and "end" to tell Pomodoro.app to actually execute those scripts.

Put this in "start" (copy, delete all text in box, then right click and choose paste) :

  do shell script "sudo /opt/caprese/caprese start DESCRIPTION=\"$pomodoroName\" DURATION=$duration"

Put this in "reset" and "end" similarly :

  do shell script "sudo /opt/caprese/caprese stop"

h3. Step 7: Profit!

The setup has a lot of steps, sorry about that. Caprese will growl an error message at you if one of the commands errored out. Please report any bugs "here":http://github.com/timcharper/caprese/issues.

h2. Credits

• Developed by Tim Harper of "Lead Media Partners":http://www.leadmediapartners.com/.
• HAS for rb-appscript and ASTranslate, invaluable tools that made this possible
• Alan Whitaker for the name