harvest-time-off 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d14f2defb88e655452e5c21a45c28586127977e4e38976628cc9caf2b4fa88d2
+  data.tar.gz: eb1f5d5c3f25a4a65e24d74aeef9a6d186248134d96c542496ac476cbe82748c
+SHA512:
+  metadata.gz: e29d62624542e6cbc648138d9ec29e998bf16469e965bc00d03b8e5b82760b21ee73848b4d0fd7c216b79239790cd3033980f85225d50a65cc8a67ccd3b63b19
+  data.tar.gz: c0c27dc68af09a0e8f6a5d1e983054ce83205b6ab0035e03d086b505d1bd7258ed600b558c60b7c7428d1bffca065855420467eba17c91cb0dc8430d6192a4ca

data/README.md

@@ -0,0 +1,63 @@
+# Harvest Time Off
+
+OMP-native Harvest integration. V1 makes holiday-aware time-off blocks convenient; it does not automate ordinary work tracking.
+
+## Credentials
+
+1. Open [Harvest ID Developers](https://id.getharvest.com/developers) and create a Personal Access Token for this local script.
+2. Harvest displays the token and the available Harvest account IDs once. Copy the account ID for the account to track time in.
+3. Fill the ignored `.envrc` in this repository:
+
+   ```bash
+   export HARVEST_ACCESS_TOKEN="your-personal-access-token"
+   export HARVEST_ACCOUNT_ID="your-harvest-account-id"
+   ```
+
+4. Run `direnv allow` if you use direnv; otherwise run `source .envrc` in the shell that starts OMP or the CLI.
+
+Personal Access Tokens are the intended Harvest authentication method for personal scripts. Revoke and replace a token from Harvest ID if it is exposed. [Harvest authentication documentation](https://help.getharvest.com/api-v2/authentication-api/authentication/authentication/).
+
+## V1: time off
+
+The approval-gated `harvest_time_off` OMP tool and `harvest-time-off` CLI create 7-hour entries for each Yukon business day in an inclusive range. They skip weekends and observed Yukon holidays by default.
+
+```bash
+harvest-time-off 2026-08-17 2026-08-28 \
+  --project 'Time Off - Marlen' \
+  --task 'Vacation / PTO' \
+  --notes 'regular time off' \
+  --dry-run
+```
+
+The default holiday region is `ca_yt`. Add `--holiday-region REGION` or set `HARVEST_HOLIDAY_REGIONS` to include other [Holidays](https://github.com/holidays/holidays) regions. `business_time` calculates business days and `holidays` supplies observed statutory holidays.
+
+A time-off block never creates weekend entries. The underlying [`marlens-harvest-api-v2`](https://github.com/klondikemarlen/harvest-api-v2) client accepts any ISO date, including weekends, for ordinary work entries.
+
+## OMP settings
+
+- `defaultHours`: hours per business day when a tool call omits `hours`; defaults to `7`.
+- `holidayRegions`: comma-separated Holidays regions; defaults to `ca_yt`.
+- `command`: direct path to the `harvest-time-off` executable.
+
+## V2: OMP Project Time integration
+
+[Issue #3](https://github.com/klondikemarlen/harvest-time-off/issues/3) tracks the next scope: turn reviewed `omp-project-time` output into Harvest work entries with configured project/task mappings, generated descriptions, duplicate/lock checks, preview, and approval. V1 remains deliberately focused on time off.
+
+## Release
+
+Before merging a release PR, self-review its complete diff, address every actionable review comment, and rerun focused QA after fixups. Record the review and QA evidence on the PR. Then merge to `main`, build and publish the Ruby gem when its `marlens-harvest-api-v2` dependency is available on RubyGems, install the released OMP plugin from GitHub, and verify it:
+
+```bash
+ruby test_harvest_time_off.rb
+npm run test:omp
+harvest-time-off 2026-08-17 2026-08-28 \
+  --project 'Time Off - Marlen' \
+  --task 'Vacation / PTO' \
+  --holiday-region ca_yt \
+  --dry-run
+gem build harvest-time-off.gemspec
+gem push harvest-time-off-<version>.gem
+omp plugin install --force github:klondikemarlen/harvest-time-off
+omp plugin list
+harvest-time-off --help
+```

data/bin/harvest-time-off

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "harvest_time_off"
+
+exit HarvestTimeOff::CLI.run(ARGV)

data/harvest-time-off.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("lib", __dir__)
+require "harvest_time_off"
+
+exit HarvestTimeOff::CLI.run(ARGV)

data/lib/harvest_time_off/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HarvestTimeOff
+  VERSION = "0.2.0"
+end

data/lib/harvest_time_off.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "harvest_time_off/version"
+require "business_time"
+require "date"
+require "holidays"
+require "optparse"
+require "marlens/harvest_api_v2"
+
+module HarvestTimeOff
+  module_function
+
+  def dates_between(from, to, holiday_regions:)
+    raise Error, "end date must not be before start date" if to < from
+    raise Error, "at least one holiday region is required" if holiday_regions.empty?
+
+    holidays = Holidays.between(from, to, *(holiday_regions.map { |region| region.downcase.to_sym } + [:observed])).map { |holiday| holiday[:date] }
+    (from..to).select { |date| date.workday?(holidays:) }
+  rescue Holidays::InvalidRegion
+    raise Error, "invalid holiday region: #{holiday_regions.join(", ")}"
+  end
+
+  def display_hours(hours)
+    format("%g", hours)
+  end
+
+  class Error < StandardError; end
+
+  class CLI
+    def self.run(arguments, output: $stdout, error: $stderr, client: nil)
+      options = { hours: 7.0, dry_run: false, holiday_regions: holiday_regions_from_environment }
+      parser = option_parser(options)
+      dates = parser.parse(arguments)
+      validate!(dates, options)
+
+      from = Date.iso8601(dates[0])
+      to = Date.iso8601(dates[1])
+      workdays = HarvestTimeOff.dates_between(from, to, holiday_regions: options[:holiday_regions])
+      raise Error, "date range contains no days to enter" if workdays.empty?
+
+      if options[:dry_run]
+        print_dry_run(output, workdays, options)
+        return 0
+      end
+
+      client ||= Marlens::HarvestApiV2::Client.from_environment
+      project_id, task_id = if options[:project_id]
+                              [options[:project_id], options[:task_id]]
+                            else
+                              resolve_assignment(client, options[:project], options[:task])
+                            end
+
+      workdays.each do |date|
+        entry = client.create_time_entry(
+          project_id:,
+          task_id:,
+          spent_date: date,
+          hours: options[:hours],
+          notes: options[:notes]
+        )
+        output.puts "Created #{date.iso8601}: #{HarvestTimeOff.display_hours(options[:hours])}h (entry ##{entry.fetch("id")})"
+      end
+      0
+    rescue Error, Marlens::HarvestApiV2::Error, OptionParser::ParseError, Date::Error => e
+      error.puts "Error: #{e.message}"
+      error.puts parser if parser
+      1
+    end
+
+    def self.option_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = <<~USAGE
+          Usage: harvest-time-off FROM TO --project NAME --task NAME [options]
+                 harvest-time-off FROM TO --project-id ID --task-id ID [options]
+
+          Creates one Harvest duration entry for each local business day from FROM through TO.
+        USAGE
+        opts.on("--project NAME", "Harvest project name") { |value| options[:project] = value }
+        opts.on("--task NAME", "Harvest task name") { |value| options[:task] = value }
+        opts.on("--project-id ID", Integer, "Harvest project ID") { |value| options[:project_id] = value }
+        opts.on("--task-id ID", Integer, "Harvest task ID") { |value| options[:task_id] = value }
+        opts.on("--hours HOURS", Float, "Hours per day (default: 7)") { |value| options[:hours] = value }
+        opts.on("--notes NOTES", "Optional note on every entry") { |value| options[:notes] = value }
+        opts.on("--holiday-region REGION", "Holidays region; repeat for each locality") { |value| options[:holiday_regions] << value.strip.downcase }
+        opts.on("--dry-run", "Print entries without calling Harvest") { options[:dry_run] = true }
+        opts.on("-h", "--help", "Show this help") do
+          puts opts
+          exit 0
+        end
+      end
+    end
+
+    def self.validate!(dates, options)
+      raise Error, "FROM and TO are required" unless dates.length == 2
+      raise Error, "--hours must be a positive finite number" unless options[:hours].positive? && options[:hours].finite?
+      raise Error, "--holiday-region or HARVEST_HOLIDAY_REGIONS is required" if options[:holiday_regions].empty?
+
+      names_provided = options[:project] || options[:task]
+      ids_provided = options[:project_id] || options[:task_id]
+      valid_names = options[:project] && options[:task]
+      valid_ids = options[:project_id] && options[:task_id]
+      raise Error, "supply --project and --task, or --project-id and --task-id" unless valid_names || valid_ids
+      raise Error, "do not combine project/task names with IDs" if names_provided && ids_provided
+    end
+
+    def self.holiday_regions_from_environment
+      ENV.fetch("HARVEST_HOLIDAY_REGIONS", "ca_yt").split(",").map { |region| region.strip.downcase }.reject(&:empty?)
+    end
+
+    def self.resolve_assignment(client, project_name, task_name)
+      # ponytail: one 2,000-item page covers personal assignments; follow cursor pagination if that ceiling is exceeded.
+      matches = client.active_task_assignments.select do |assignment|
+        assignment.dig("project", "name")&.casecmp?(project_name) &&
+          assignment.dig("task", "name")&.casecmp?(task_name)
+      end
+
+      return [matches.first.dig("project", "id"), matches.first.dig("task", "id")] if matches.one?
+
+      qualifier = "project #{project_name.inspect} and task #{task_name.inspect}"
+      raise Error, "No active task assignment matches #{qualifier}. Pass --project-id and --task-id instead." if matches.empty?
+
+      raise Error, "Multiple active task assignments match #{qualifier}. Pass --project-id and --task-id instead."
+    end
+
+    def self.print_dry_run(output, dates, options)
+      project = options[:project] || "project ##{options[:project_id]}"
+      task = options[:task] || "task ##{options[:task_id]}"
+      notes = options[:notes] ? "; #{options[:notes]}" : ""
+      dates.each do |date|
+        output.puts "Would create #{date.iso8601}: #{HarvestTimeOff.display_hours(options[:hours])}h on #{project} / #{task}#{notes}"
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: harvest-time-off
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Marlen Brunner
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: marlens-harvest-api-v2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: business_time
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: holidays
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.2'
+email:
+- klondikemarlen@gmail.com
+executables:
+- harvest-time-off
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/harvest-time-off
+- harvest-time-off.rb
+- lib/harvest_time_off.rb
+- lib/harvest_time_off/version.rb
+homepage: https://github.com/klondikemarlen/harvest-time-off
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/klondikemarlen/harvest-time-off
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Create Harvest time-off entries over a date range.
+test_files: []