harvest-worklog 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1397fdec13d0a89c0023e926fa42043f701c351e0fbca487e40331c61bbfbcf
-  data.tar.gz: '09b9a725ea95df79e94cf204a1f12735c6db8e4d55d4a38f8442fc3f947f981f'
+  metadata.gz: bd656e6ca496a7a7a5d08e0e1f407c5aaf030b80c75751abd354ce1259a3806d
+  data.tar.gz: cf38ac55098c083668f3df37774298c21b6329c39a6d017d1968fce9227bfd30
 SHA512:
-  metadata.gz: 33f8bbfa7e4d6f4b98bcc014d6ba3cdb51193a2582a3fd3bed37e3d4051fb606440065f60076d9afd1efc9ab64aa4d6f14a4d6fdb4dd0ff92775419a34012d74
-  data.tar.gz: 32d59d73fc353d159e7e7a6c93373147f0a7756b4f3b0ba56b4bb877b2cd177000ee8898739eeb1813c3830640cb8a6ce57d1272ab9aa1a5f1bdec1146f3adf9
+  metadata.gz: 72a0dc46a8551f9f3a6e8efd7bffd6ee9a2bbaf34021f86cdd98c0dc356d08edd88e96aa0da3e992b59f7ec5794f1656f2a3c785ebf7bc002f99c6a0f06e550b
+  data.tar.gz: 8fae9c3ecd9f91ac43280b854715532c4ea86221a9381793fea2674800e54d4577962e7a1adc8829a545544ff6b578727aee1396f979ccc4c02c554ad68f9121

data/README.md

@@ -22,6 +22,7 @@ Personal Access Tokens are the intended Harvest authentication method for person
 ```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]
+harvest-worklog aggregate FROM TO [--project NAME] [--task NAME]
 ```
 
 ### Time off
@@ -44,6 +45,18 @@ A time-off block never creates weekend entries. When names are supplied, it reso
 
 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.
 
+### Read-only aggregates
+
+The `aggregate` command reads all matching Harvest time-entry pages and prints totals grouped by spent date and project/task. It lists every date in the inclusive range, including weekend or empty dates, and never writes a Harvest record.
+
+```bash
+harvest-worklog aggregate 2026-07-17 2026-07-19 \
+  --project WRAP \
+  --task Programming
+```
+
+The `harvest_time_aggregates` OMP tool exposes the same optional filters and is approval-gated as a read.
+
 ## OMP settings
 
 - `defaultHours`: hours per business day when a time-off tool call omits `hours`; defaults to `7`.
@@ -64,6 +77,26 @@ Configure `projectTimeMappings` with the recorded OMP Project Time project name
 
 `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.
 
+### Activity transforms
+
+`harvest_preview_project_time_transforms` emits deterministic JSON for local raw intervals. It accepts an inclusive date range and optional exact `repositoryId`, `project`, and `sourceKind` filters; each matching interval is split by local date and grouped by activity, with missing labels reported as `unlabelled`. Set `applyMappings` to include configured Harvest project/task mappings. The output reports `groups`, proposed mapped `entries`, and any `unmapped` or `excluded` rows.
+
+`harvest_record_project_time_transforms` is a separate approval-gated write step. It always applies configured mappings and records the reviewed activity entries through the existing locked and duplicate preflight. Different activity labels may share a date/project/task; rerunning the same activity label is skipped, as are locked or unrelated existing entries.
+
+## Reconciling WRAP hours with manual entries
+
+Use a closed date range and record the expected OMP Project Time and manually entered hours for each day. Preview OMP entries first, then compare the final Harvest total for each day:
+
+```bash
+harvest-worklog aggregate FROM TO \
+  --project WRAP \
+  --task Programming
+```
+
+OMP-created entries use an `OMP Project Time:` note; use a `Manual reconciliation:` note for manual entries while testing. Inspect the Harvest entry details to distinguish their source—the aggregate intentionally combines all matching entries.
+
+The standard work-entry importer allows only one entry for a date, project, and task. If a manual `WRAP / Programming` entry exists for a date, importing ordinary OMP Project Time for that same mapping skips it rather than adding hours. Activity transforms are the exception: distinct activity labels can create separate entries while the same label, locked entries, and unrelated manual entries are still skipped. Reconcile ordinary entries as either OMP or manual hours, not their sum.
+
 ## 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.
@@ -80,8 +113,11 @@ harvest-worklog time-off 2026-08-17 2026-08-28 \
   --task 'Vacation / PTO' \
   --holiday-region ca_yt \
   --dry-run
+VERSION="$(ruby -Ilib -rharvest_worklog/version -e 'puts HarvestWorklog::VERSION')"
 gem build harvest-worklog.gemspec
-gem push harvest-worklog-<version>.gem
+gem push "harvest-worklog-${VERSION}.gem"
+gem uninstall harvest-time-off --all --executables --ignore-dependencies
+gem install --clear-sources --source https://rubygems.org harvest-worklog --version "$VERSION" --no-document
 omp plugin uninstall harvest-time-off
 omp plugin install --force github:klondikemarlen/harvest-worklog
 omp plugin list

data/lib/harvest_worklog/aggregate_cli.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module HarvestWorklog
+  class AggregateCLI
+    PER_PAGE = 100
+
+    def self.run(arguments, output: $stdout, error: $stderr, client: nil)
+      options = {}
+      parser = option_parser(options)
+      dates = parser.parse(arguments)
+      validate!(dates)
+
+      from = Date.iso8601(dates[0])
+      to = Date.iso8601(dates[1])
+      raise Error, "end date must not be before start date" if to < from
+
+      client ||= Marlens::HarvestApiV2::Client.from_environment
+      entries = fetch_entries(client, from:, to:).select { |entry| matches?(entry, options) }
+      print_summary(output, entries, from:, to:)
+      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 aggregate FROM TO [--project NAME] [--task NAME]"
+        opts.on("--project NAME", "Filter by Harvest project name") { |value| options[:project] = value }
+        opts.on("--task NAME", "Filter by Harvest task name") { |value| options[:task] = value }
+        opts.on("-h", "--help", "Show this help") do
+          puts opts
+          exit 0
+        end
+      end
+    end
+
+    def self.validate!(dates)
+      raise Error, "FROM and TO are required" unless dates.length == 2
+    end
+
+    def self.fetch_entries(client, from:, to:)
+      entries = []
+      page = 1
+      loop do
+        response = client.request(
+          :get,
+          "/v2/time_entries",
+          params: { from: from.iso8601, to: to.iso8601, page:, per_page: PER_PAGE }
+        )
+        entries.concat(response.fetch("time_entries"))
+        page = response["next_page"]
+        break if page.nil?
+      end
+      entries
+    end
+
+    def self.matches?(entry, options)
+      name_matches?(entry.dig("project", "name"), options[:project]) &&
+        name_matches?(entry.dig("task", "name"), options[:task])
+    end
+
+    def self.name_matches?(actual, expected)
+      expected.nil? || actual&.casecmp?(expected)
+    end
+
+    def self.print_summary(output, entries, from:, to:)
+      output.puts "#{entries.length} #{entry_label(entries.length)}, #{HarvestWorklog.display_hours(total_hours(entries))}h from #{from.iso8601} through #{to.iso8601}"
+      output.puts "By date:"
+      (from..to).each do |date|
+        date_entries = entries.select { |entry| entry.fetch("spent_date") == date.iso8601 }
+        output.puts "  #{date.iso8601}: #{date_entries.length} #{entry_label(date_entries.length)}, #{HarvestWorklog.display_hours(total_hours(date_entries))}h"
+      end
+      output.puts "By project/task:"
+
+      groups = entries.group_by { |entry| [entry.dig("project", "name"), entry.dig("task", "name")] }
+      if groups.empty?
+        output.puts "  none"
+        return
+      end
+
+      groups.keys.sort_by { |project, task| [project.downcase, task.downcase] }.each do |project, task|
+        group = groups.fetch([project, task])
+        output.puts "  #{project} / #{task}: #{group.length} #{entry_label(group.length)}, #{HarvestWorklog.display_hours(total_hours(group))}h"
+      end
+    end
+
+    def self.total_hours(entries)
+      entries.sum { |entry| Float(entry.fetch("hours")) }
+    end
+
+    def self.entry_label(count)
+      count == 1 ? "entry" : "entries"
+    end
+  end
+end

data/lib/harvest_worklog/version.rb

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

data/lib/harvest_worklog/work_entry_cli.rb

@@ -6,7 +6,7 @@ module HarvestWorklog
     LOCKED_ENTRY = 3
 
     def self.run(arguments, output: $stdout, error: $stderr, client: nil)
-      options = { dry_run: false }
+      options = { dry_run: false, activity_entry: false }
       parser = option_parser(options)
       dates = parser.parse(arguments)
       validate!(dates, options)
@@ -29,7 +29,14 @@ module HarvestWorklog
         return LOCKED_ENTRY
       end
 
-      if existing_entries.any?
+      if options[:activity_entry]
+        activity_key = options[:notes].lines.first
+        unrelated_entries = existing_entries.reject { |entry| entry["notes"]&.lines&.first&.start_with?("OMP Project Time activity: ") }
+        if unrelated_entries.any? || existing_entries.any? { |entry| entry["notes"]&.lines&.first == activity_key }
+          output.puts "Existing Harvest entry on #{spent_date.iso8601}; skipped"
+          return EXISTING_ENTRY
+        end
+      elsif existing_entries.any?
         output.puts "Existing Harvest entry on #{spent_date.iso8601}; skipped"
         return EXISTING_ENTRY
       end
@@ -64,6 +71,7 @@ module HarvestWorklog
         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("--activity-entry", "Allow distinct OMP Project Time activity entries on the same date, project, and task") { options[:activity_entry] = true }
         opts.on("-h", "--help", "Show this help") do
           puts opts
           exit 0

data/lib/harvest_worklog.rb

@@ -34,11 +34,13 @@ module HarvestWorklog
         TimeOffCLI.run(command_arguments, output:, error:, client:)
       when "work-entry"
         WorkEntryCLI.run(command_arguments, output:, error:, client:)
+      when "aggregate"
+        AggregateCLI.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 "Error: choose time-off, work-entry, or aggregate"
         error.puts usage
         1
       end
@@ -49,10 +51,12 @@ module HarvestWorklog
         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]
+          harvest-worklog aggregate FROM TO [--project NAME] [--task NAME]
 
         Commands:
           time-off    Create one entry per local business day in a date range.
           work-entry  Create one reviewed ordinary-work entry.
+          aggregate   Read time-entry totals without writing Harvest records.
       USAGE
     end
   end
@@ -165,3 +169,4 @@ module HarvestWorklog
 end
 
 require "harvest_worklog/work_entry_cli"
+require "harvest_worklog/aggregate_cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: harvest-worklog
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Marlen Brunner
@@ -62,6 +62,7 @@ files:
 - bin/harvest-worklog
 - harvest-worklog.rb
 - lib/harvest_worklog.rb
+- lib/harvest_worklog/aggregate_cli.rb
 - lib/harvest_worklog/version.rb
 - lib/harvest_worklog/work_entry_cli.rb
 homepage: https://github.com/klondikemarlen/harvest-worklog