harvest-worklog 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1397fdec13d0a89c0023e926fa42043f701c351e0fbca487e40331c61bbfbcf
+  data.tar.gz: '09b9a725ea95df79e94cf204a1f12735c6db8e4d55d4a38f8442fc3f947f981f'
+SHA512:
+  metadata.gz: 33f8bbfa7e4d6f4b98bcc014d6ba3cdb51193a2582a3fd3bed37e3d4051fb606440065f60076d9afd1efc9ab64aa4d6f14a4d6fdb4dd0ff92775419a34012d74
+  data.tar.gz: 32d59d73fc353d159e7e7a6c93373147f0a7756b4f3b0ba56b4bb877b2cd177000ee8898739eeb1813c3830640cb8a6ce57d1272ab9aa1a5f1bdec1146f3adf9

data/README.md

@@ -0,0 +1,89 @@
+# Harvest Worklog
+
+Harvest Worklog is a Ruby CLI and OMP plugin for personal Harvest work logs. It creates holiday-aware time-off entries, writes reviewed ordinary-work entries, and imports reviewed OMP Project Time sessions.
+
+## Credentials
+
+1. Open [Harvest ID Developers](https://id.getharvest.com/developers) and create a Personal Access Token for this local tool.
+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/).
+
+## CLI
+
+```text
+harvest-worklog time-off FROM TO --project NAME --task NAME [options]
+harvest-worklog work-entry DATE --project NAME --task NAME --hours HOURS --notes NOTES [options]
+```
+
+### Time off
+
+The `time-off` command creates one 7-hour entry for each Yukon business day in an inclusive range. It skips weekends and observed Yukon holidays by default.
+
+```bash
+harvest-worklog 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. When names are supplied, it resolves them from your active personal Harvest assignments, so a Project Manager role is not required.
+
+### Reviewed ordinary work
+
+The `work-entry` command checks for existing or locked entries for its project, task, and date before creating a new duration entry. Use `--dry-run` to complete that preflight without a write. OMP Project Time uses the same path.
+
+## OMP settings
+
+- `defaultHours`: hours per business day when a time-off tool call omits `hours`; defaults to `7`.
+- `holidayRegions`: comma-separated Holidays regions; defaults to `ca_yt`.
+- `command`: direct path to the `harvest-worklog` executable.
+- `projectTimeMappings`: JSON mapping from OMP Project Time project names to Harvest project/task names.
+- `projectTimeLogPath`: optional override for `~/.omp/project-time/time-log.json`.
+
+## OMP Project Time integration
+
+Configure `projectTimeMappings` with the recorded OMP Project Time project name as the key:
+
+```json
+{
+  "Harvest API": { "project": "Internal", "task": "Development" }
+}
+```
+
+`harvest_preview_project_time_entries` reads the configured time log, splits sessions across local dates, generates descriptions from the project and repository, and checks Harvest for existing or locked entries without writing. `harvest_record_project_time_entries` performs the same preflight then creates only new entries; OMP treats it as a write requiring approval. Unmapped sessions are reported and never written.
+
+## Migration from harvest-time-off
+
+Version `0.5.0` is a clean identity cutover. Uninstall the prior `harvest-time-off` gem and OMP plugin, then install `harvest-worklog`; replace former top-level CLI commands with the `harvest-worklog time-off` and `harvest-worklog work-entry` subcommands. The old package, executables, and `workEntryCommand` setting are not retained.
+
+## 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, install the released OMP plugin from GitHub, and verify it:
+
+```bash
+ruby test_harvest_worklog.rb
+npm run test:omp
+harvest-worklog time-off 2026-08-17 2026-08-28 \
+  --project 'Time Off - Marlen' \
+  --task 'Vacation / PTO' \
+  --holiday-region ca_yt \
+  --dry-run
+gem build harvest-worklog.gemspec
+gem push harvest-worklog-<version>.gem
+omp plugin uninstall harvest-time-off
+omp plugin install --force github:klondikemarlen/harvest-worklog
+omp plugin list
+harvest-worklog --help
+```

data/bin/harvest-worklog

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

data/harvest-worklog.rb

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

data/lib/harvest_worklog/version.rb

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

data/lib/harvest_worklog/work_entry_cli.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module HarvestWorklog
+  class WorkEntryCLI
+    EXISTING_ENTRY = 2
+    LOCKED_ENTRY = 3
+
+    def self.run(arguments, output: $stdout, error: $stderr, client: nil)
+      options = { dry_run: false }
+      parser = option_parser(options)
+      dates = parser.parse(arguments)
+      validate!(dates, options)
+
+      spent_date = Date.iso8601(dates.first)
+      client ||= Marlens::HarvestApiV2::Client.from_environment
+      project_id, task_id = if options[:project_id]
+                              [options[:project_id], options[:task_id]]
+                            else
+                              TimeOffCLI.resolve_assignment(client, options[:project], options[:task])
+                            end
+      existing_entries = client.request(
+        :get,
+        "/v2/time_entries",
+        params: { project_id:, task_id:, from: spent_date.iso8601, to: spent_date.iso8601 }
+      ).fetch("time_entries")
+
+      if existing_entries.any? { |entry| entry["is_locked"] }
+        output.puts "Locked existing Harvest entry on #{spent_date.iso8601}; skipped"
+        return LOCKED_ENTRY
+      end
+
+      if existing_entries.any?
+        output.puts "Existing Harvest entry on #{spent_date.iso8601}; skipped"
+        return EXISTING_ENTRY
+      end
+
+      if options[:dry_run]
+        output.puts "Would create #{spent_date.iso8601}: #{HarvestWorklog.display_hours(options[:hours])}h on #{options[:project]} / #{options[:task]}; #{options[:notes]}"
+        return 0
+      end
+
+      entry = client.create_time_entry(
+        project_id:,
+        task_id:,
+        spent_date:,
+        hours: options[:hours],
+        notes: options[:notes]
+      )
+      output.puts "Created #{spent_date.iso8601}: #{HarvestWorklog.display_hours(options[:hours])}h (entry ##{entry.fetch("id")})"
+      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: harvest-worklog work-entry DATE --project NAME --task NAME --hours HOURS --notes NOTES [--dry-run]"
+        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 for this entry") { |value| options[:hours] = value }
+        opts.on("--notes NOTES", "Entry description") { |value| options[:notes] = value }
+        opts.on("--dry-run", "Check for existing entries without writing") { 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, "DATE is required" unless dates.length == 1
+      raise Error, "--hours must be a positive finite number" unless options[:hours]&.positive? && options[:hours].finite?
+      raise Error, "--notes is required" unless options[:notes] && !options[:notes].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
+  end
+end

data/lib/harvest_worklog.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "harvest_worklog/version"
+require "business_time"
+require "date"
+require "holidays"
+require "optparse"
+require "marlens/harvest_api_v2"
+
+module HarvestWorklog
+  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)
+      command, *command_arguments = arguments
+      case command
+      when "time-off"
+        TimeOffCLI.run(command_arguments, output:, error:, client:)
+      when "work-entry"
+        WorkEntryCLI.run(command_arguments, output:, error:, client:)
+      when "-h", "--help"
+        output.puts usage
+        0
+      else
+        error.puts "Error: choose time-off or work-entry"
+        error.puts usage
+        1
+      end
+    end
+
+    def self.usage
+      <<~USAGE
+        Usage:
+          harvest-worklog time-off FROM TO --project NAME --task NAME [options]
+          harvest-worklog work-entry DATE --project NAME --task NAME --hours HOURS --notes NOTES [options]
+
+        Commands:
+          time-off    Create one entry per local business day in a date range.
+          work-entry  Create one reviewed ordinary-work entry.
+      USAGE
+    end
+  end
+
+  class TimeOffCLI
+    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 = HarvestWorklog.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}: #{HarvestWorklog.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-worklog time-off FROM TO --project NAME --task NAME [options]
+                 harvest-worklog 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_personal_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}: #{HarvestWorklog.display_hours(options[:hours])}h on #{project} / #{task}#{notes}"
+      end
+    end
+  end
+end
+
+require "harvest_worklog/work_entry_cli"

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: harvest-worklog
+version: !ruby/object:Gem::Version
+  version: 0.5.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.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !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-worklog
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/harvest-worklog
+- harvest-worklog.rb
+- lib/harvest_worklog.rb
+- lib/harvest_worklog/version.rb
+- lib/harvest_worklog/work_entry_cli.rb
+homepage: https://github.com/klondikemarlen/harvest-worklog
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/klondikemarlen/harvest-worklog
+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: Harvest work-log CLI and OMP integration.
+test_files: []