harvest-worklog 0.10.6 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e46ca248b7d1ec0b17de75c726874d41c653182f7ca51437e3ffff95210869f
-  data.tar.gz: db4d6e6e123df77a7ba7cc0996a356d79140402a23d2dca0598665e29b5a1a99
+  metadata.gz: 65c8eff780c91f0fc513e021af972f0a2b72a51a0a0b5d80a1854c112816a8e7
+  data.tar.gz: 708ec5a2a2b7bda162623c2694eca533431dd7fe0592560bc97300c4614fa59d
 SHA512:
-  metadata.gz: 6022e40a5eed269ac42eb089b9fc858b616b7fb7515a009489830600b9b39ad2fdaf138b6fb3ea36df17a7bac855e502d9dcae6aa51eca7a5033ff4a9bb88e90
-  data.tar.gz: 4abaec9e28c59ef818e7fd3c6471d9fa4d8ea4b067adf43925fcca43ea835e255164836bcc8069af23d9b18e9b5c071bac7f1de2e044907ed117b6cc62355969
+  metadata.gz: 745e280ee770aa2ade4d0ae89cdb4c32aa656fe71290dcf7298c9521cc09ba59dda948d48449008cce8a0029e701680039f8d8238114b8fe9eea350a54e00698
+  data.tar.gz: c07e15b6ffb42f580a9591726af256e27f06624bad2e8c8ed4c5ff62d6860a37b26787f6943e35b8cd1bed9a09f20a79f8e63b4b229b678093eb90e889d36108

data/README.md

@@ -26,6 +26,7 @@ harvest-worklog work-entry DATE --project NAME --task NAME --hours HOURS --notes
 harvest-worklog work-entry DATE --project-id ID --task-id ID --hours HOURS --notes NOTES [options]
 harvest-worklog aggregate FROM TO [--project NAME] [--task NAME]
 harvest-worklog timesheet DATE --project NAME [--task NAME]
+harvest-worklog reconcile DATE --project PROJECT --harvest-project NAME [--task NAME]
 ```
 
 ### Time off
@@ -93,25 +94,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.
+`harvest_preview_project_time_entries` reads only `human_active` sessions from the configured time log, splits them across local dates, reports that source policy, 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_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`. It defaults to `human_active` and returns the effective top-level `sourceKind`; selecting `agent_turn_elapsed` requires an explicit source-kind request. 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
+## Daily reconciliation
 
-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:
+`reconcile` compares one local Project Time project against the manual Harvest total for one date. It reads only local `human_active` intervals, reports the raw duration, non-overlapping union, concurrent overlap, and both Harvest-minus-local deltas. It never creates or changes Harvest entries: manual Harvest is the benchmark.
 
 ```bash
-harvest-worklog aggregate FROM TO \
-  --project WRAP \
+harvest-worklog reconcile 2026-07-21 \
+  --project wrap \
+  --harvest-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.
+Empty local or Harvest data is reported as zero, so this command is suitable for daily capture checks while manual tracking remains authoritative. [#51](https://github.com/klondikemarlen/harvest-worklog/issues/51) separately ensures ordinary automatic exports use only the same `human_active` evidence.
 
 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.
 

data/lib/harvest_worklog/reconcile_cli.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module HarvestWorklog
+  class ReconcileCLI
+    def self.run(arguments, output: $stdout, error: $stderr, client: nil, log_path: default_log_path, today: Date.today)
+      options = {}
+      parser = option_parser(options)
+      dates = parser.parse(arguments)
+      validate!(dates, options)
+
+      date = TimesheetCLI.resolve_date(dates.first, today:)
+      client ||= Marlens::HarvestApiV2::Client.from_environment
+      user_id = TimesheetCLI.current_user_id(client)
+      harvest_entries = AggregateCLI.fetch_entries(client, from: date, to: date, user_id:).select do |entry|
+        AggregateCLI.matches?(entry, project: options[:harvest_project], task: options[:task])
+      end
+      print_reconciliation(
+        output,
+        date:,
+        local_project: options[:project],
+        intervals: local_intervals(log_path, date:, project: options[:project]),
+        harvest_entries:
+      )
+      0
+    rescue Error, Marlens::HarvestApiV2::Error, OptionParser::ParseError, Date::Error, Errno::ENOENT, JSON::ParserError => 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 reconcile DATE --project PROJECT --harvest-project NAME [--task NAME]"
+        opts.on("--project NAME", "Filter local OMP Project Time project name") { |value| options[:project] = value }
+        opts.on("--harvest-project NAME", "Filter manual Harvest project name") { |value| options[:harvest_project] = value }
+        opts.on("--task NAME", "Filter manual 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, options)
+      raise Error, "DATE is required" unless dates.length == 1
+      %i[project harvest_project].each do |name|
+        raise Error, "--#{name.to_s.tr('_', '-')} is required" unless options[name]&.strip&.length&.positive?
+      end
+      raise Error, "--task must not be blank" if options[:task]&.strip&.empty?
+    end
+
+    def self.default_log_path
+      File.join(Dir.home, ".omp", "project-time", "time-log.json")
+    end
+
+    def self.local_intervals(log_path, date:, project:)
+      state = JSON.parse(File.read(log_path))
+      entries = state.is_a?(Hash) ? state["entries"] : nil
+      raise Error, "OMP Project Time log is missing an entries array" unless entries.is_a?(Array)
+
+      day_start = Time.local(date.year, date.month, date.day).to_f * 1000
+      next_date = date + 1
+      day_end = Time.local(next_date.year, next_date.month, next_date.day).to_f * 1000
+      entries.filter_map do |entry|
+        next unless entry.is_a?(Hash) && entry["sourceKind"] == "human_active" && entry["project"] == project
+
+        start_at = entry["startAtMs"]
+        end_at = entry["endAtMs"]
+        raise Error, "OMP Project Time log contains an invalid session interval" unless start_at.is_a?(Numeric) && end_at.is_a?(Numeric) && start_at < end_at
+
+        start_at = [start_at, day_start].max
+        end_at = [end_at, day_end].min
+        [start_at, end_at] if start_at < end_at
+      end
+    end
+
+    def self.print_reconciliation(output, date:, local_project:, intervals:, harvest_entries:)
+      raw = intervals.sum { |start_at, end_at| end_at - start_at }
+      union = merged_duration(intervals)
+      harvest = AggregateCLI.total_hours(harvest_entries) * 3_600_000
+
+      output.puts "#{date.iso8601} reconciliation"
+      output.puts "Manual Harvest: #{duration(harvest)} (#{harvest_entries.length} #{AggregateCLI.entry_label(harvest_entries.length)})"
+      output.puts "Local OMP Project Time #{local_project}:"
+      output.puts "  Raw intervals: #{duration(raw)}"
+      output.puts "  Non-overlapping union: #{duration(union)}"
+      output.puts "  Concurrent overlap: #{duration(raw - union)}"
+      output.puts "Harvest minus local raw: #{signed_duration(harvest - raw)}"
+      output.puts "Harvest minus local union: #{signed_duration(harvest - union)}"
+      output.puts "Verdict: Manual Harvest is the benchmark. This read-only comparison creates or changes no entries."
+    end
+
+    def self.merged_duration(intervals)
+      merged = intervals.sort_by(&:first).each_with_object([]) do |(start_at, end_at), result|
+        if result.empty? || start_at > result.last.last
+          result << [start_at, end_at]
+        else
+          result.last[1] = [result.last[1], end_at].max
+        end
+      end
+      merged.sum { |start_at, end_at| end_at - start_at }
+    end
+
+    def self.signed_duration(milliseconds)
+      seconds = (milliseconds / 1000.0).round
+      return duration(0) if seconds.zero?
+
+      "#{seconds.negative? ? '-' : '+'}#{duration(seconds.abs * 1000)}"
+    end
+
+    def self.duration(milliseconds)
+      seconds = (milliseconds / 1000.0).round
+      "%dh %dm %ds" % [seconds / 3600, seconds / 60 % 60, seconds % 60]
+    end
+  end
+end

data/lib/harvest_worklog/version.rb

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

data/lib/harvest_worklog.rb

@@ -39,13 +39,15 @@ module HarvestWorklog
         AggregateCLI.run(command_arguments, output:, error:, client:)
       when "timesheet"
         TimesheetCLI.run(command_arguments, output:, error:, client:)
+      when "reconcile"
+        ReconcileCLI.run(command_arguments, output:, error:, client:)
       when "mapping-data"
         MappingDataCLI.run(command_arguments, output:, error:, client:)
       when "-h", "--help"
         output.puts usage
         0
       else
-        error.puts "Error: choose time-off, work-entry, aggregate, timesheet, or mapping-data"
+        error.puts "Error: choose time-off, work-entry, aggregate, timesheet, reconcile, or mapping-data"
         error.puts usage
         1
       end
@@ -60,6 +62,7 @@ module HarvestWorklog
           harvest-worklog work-entry DATE --project-id ID --task-id ID --hours HOURS --notes NOTES [options]
           harvest-worklog aggregate FROM TO [--project NAME] [--task NAME]
           harvest-worklog timesheet DATE --project NAME [--task NAME]
+          harvest-worklog reconcile DATE --project PROJECT --harvest-project NAME [--task NAME]
           harvest-worklog mapping-data FROM TO
 
         Commands:
@@ -67,6 +70,7 @@ module HarvestWorklog
           work-entry  Create one reviewed ordinary-work entry.
           aggregate   Read time-entry totals without writing Harvest records.
           timesheet  Read a compact daily project timesheet without writing Harvest records.
+          reconcile   Compare local Project Time with manual Harvest without writing.
           mapping-data Read assigned Harvest destinations and historical entries without writing.
       USAGE
     end
@@ -191,4 +195,5 @@ end
 require "harvest_worklog/work_entry_cli"
 require "harvest_worklog/aggregate_cli"
 require "harvest_worklog/timesheet_cli"
+require "harvest_worklog/reconcile_cli"
 require "harvest_worklog/mapping_data_cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: harvest-worklog
 version: !ruby/object:Gem::Version
-  version: 0.10.6
+  version: 0.12.0
 platform: ruby
 authors:
 - Marlen Brunner
@@ -66,6 +66,7 @@ files:
 - lib/harvest_worklog.rb
 - lib/harvest_worklog/aggregate_cli.rb
 - lib/harvest_worklog/mapping_data_cli.rb
+- lib/harvest_worklog/reconcile_cli.rb
 - lib/harvest_worklog/timesheet_cli.rb
 - lib/harvest_worklog/version.rb
 - lib/harvest_worklog/work_entry_cli.rb