na 1.2.86 → 1.2.87

data/lib/na/next_action.rb

@@ -327,7 +327,22 @@ module NA
                       move: nil,
                       remove_tag: [],
                       replace: nil,
-                      tagged: nil)
+                      tagged: nil,
+                      started_at: nil,
+                      done_at: nil,
+                      duration_seconds: nil)
+      # Coerce date/time inputs if passed as strings
+      begin
+        started_at = NA::Types.parse_date_begin(started_at) if started_at && !started_at.is_a?(Time)
+      rescue StandardError
+        # leave as-is
+      end
+      begin
+        done_at = NA::Types.parse_date_end(done_at) if done_at && !done_at.is_a?(Time)
+      rescue StandardError
+        # leave as-is
+      end
+      NA.notify("UPDATE parsed started_at=#{started_at.inspect} done_at=#{done_at.inspect} duration=#{duration_seconds.inspect}", debug: true)
       # Expand target to absolute path to avoid path resolution issues
       target = File.expand_path(target) unless Pathname.new(target).absolute?
 
@@ -359,12 +374,20 @@ module NA
         # So we don't need to handle it here - the action is already edited
 
         add_tag ||= []
-        add.process(priority: priority, finish: finish, add_tag: add_tag, remove_tag: remove_tag)
-
-        # Remove the original action and its notes
+        NA.notify("PROCESS before add.process started_at=#{started_at.inspect} done_at=#{done_at.inspect}", debug: true)
+        add.process(priority: priority,
+                    finish: finish,
+                    add_tag: add_tag,
+                    remove_tag: remove_tag,
+                    started_at: started_at,
+                    done_at: done_at,
+                    duration_seconds: duration_seconds)
+        NA.notify("PROCESS after add.process action=\"#{add.action}\"", debug: true)
+
+        # Remove the original action and its notes if this is an existing action
         action_line = add.file_line
         note_lines = add.note.is_a?(Array) ? add.note.count : 0
-        contents.slice!(action_line, note_lines + 1)
+        contents.slice!(action_line, note_lines + 1) if action_line.is_a?(Integer)
 
         # Prepare updated note
         note = note.to_s.split("\n") unless note.is_a?(Array)
@@ -384,32 +407,52 @@ module NA
         # Format note for insertion
         note_str = updated_note.empty? ? '' : "\n#{indent}\t\t#{updated_note.join("\n#{indent}\t\t").strip}"
 
-        # Insert at correct location: if moving, insert at start/end of target project
-        if move && target_proj
-          insert_line = if append
-                          # End of project
-                          target_proj.last_line + 1
-                        else
-                          # Start of project (after project header)
-                          target_proj.line + 1
-                        end
-          contents.insert(insert_line, "#{indent}\t- #{add.action}#{note_str}")
+        # If delete was requested in this direct update path, do not re-insert
+        if delete
+          affected_actions << { action: add, desc: 'deleted' }
         else
-          # Not moving, update in-place
-          contents.insert(action_line, "#{indent}\t- #{add.action}#{note_str}")
-        end
+          # Insert at correct location
+          if target_proj
+            insert_line = if append
+                            # End of project
+                            target_proj.last_line + 1
+                          else
+                            # Start of project (after project header)
+                            target_proj.line + 1
+                          end
+            # Ensure @started tag persists if provided
+            final_action = add.action.dup
+            if started_at && final_action !~ /(?<=\A| )@start(?:ed)?\(/i
+              final_action = final_action.gsub(/(?<=\A| )@start(?:ed)?\(.*?\)/i, '').strip
+              final_action = "#{final_action} @started(#{started_at.strftime('%Y-%m-%d %H:%M')})"
+            end
+            NA.notify("INSERT at #{insert_line} final_action=\"#{final_action}\"", debug: true)
+            contents.insert(insert_line, "#{indent}\t- #{final_action}#{note_str}")
+          else
+            # Fallback: append to end of file
+            final_action = add.action.dup
+            if started_at && final_action !~ /(?<=\A| )@start(?:ed)?\(/i
+              final_action = final_action.gsub(/(?<=\A| )@start(?:ed)?\(.*?\)/i, '').strip
+              final_action = "#{final_action} @started(#{started_at.strftime('%Y-%m-%d %H:%M')})"
+            end
+            NA.notify("APPEND final_action=\"#{final_action}\"", debug: true)
+            contents << "#{indent}\t- #{final_action}#{note_str}"
+          end
 
-        notify(add.pretty)
+          notify(add.pretty)
+        end
 
         # Track affected action and description
-        changes = ['updated']
-        changes << 'finished' if finish
-        changes << "priority=#{priority}" if priority.to_i.positive?
-        changes << "tags+#{add_tag.join(',')}" unless add_tag.nil? || add_tag.empty?
-        changes << "tags-#{remove_tag.join(',')}" unless remove_tag.nil? || remove_tag.empty?
-        changes << 'note updated' unless note.nil? || note.empty?
-        changes << "moved to #{target_proj.project}" if move && target_proj
-        affected_actions << { action: add, desc: changes.join(', ') }
+        unless delete
+          changes = ['updated']
+          changes << 'finished' if finish
+          changes << "priority=#{priority}" if priority.to_i.positive?
+          changes << "tags+#{add_tag.join(',')}" unless add_tag.nil? || add_tag.empty?
+          changes << "tags-#{remove_tag.join(',')}" unless remove_tag.nil? || remove_tag.empty?
+          changes << 'note updated' unless note.nil? || note.empty?
+          changes << "moved to #{target_proj.project}" if move && target_proj
+          affected_actions << { action: add, desc: changes.join(', ') }
+        end
       else
         # Check if search is actually target_line
         target_line = search.is_a?(Hash) && search[:target_line] ? search[:target_line] : nil
@@ -445,7 +488,13 @@ module NA
           # If replace is defined, use search to search and replace text in action
           action.action.sub!(Regexp.new(Regexp.escape(search), Regexp::IGNORECASE), replace) if replace
 
-          action.process(priority: priority, finish: finish, add_tag: add_tag, remove_tag: remove_tag)
+          action.process(priority: priority,
+                         finish: finish,
+                         add_tag: add_tag,
+                         remove_tag: remove_tag,
+                         started_at: started_at,
+                         done_at: done_at,
+                         duration_seconds: duration_seconds)
 
           target_proj = if target_proj
                           projects.select { |proj| proj.project =~ /^#{target_proj.project}$/ }.first
@@ -532,7 +581,7 @@ module NA
     # @param finish [Boolean] Mark as finished
     # @param append [Boolean] Append to project
     # @return [void]
-    def add_action(file, project, action, note = [], priority: 0, finish: false, append: false)
+    def add_action(file, project, action, note = [], priority: 0, finish: false, append: false, started_at: nil, done_at: nil, duration_seconds: nil)
       parent = project.split(%r{[:/]})
 
       if NA.global_file
@@ -545,8 +594,16 @@ module NA
 
       action = Action.new(file, project, parent, action, nil, note)
 
-      update_action(file, nil, add: action, project: project, add_tag: add_tag, priority: priority, finish: finish,
-                               append: append)
+      update_action(file, nil,
+                    add: action,
+                    project: project,
+                    add_tag: add_tag,
+                    priority: priority,
+                    finish: finish,
+                    append: append,
+                    started_at: started_at,
+                    done_at: done_at,
+                    duration_seconds: duration_seconds)
     end
 
     # Build a nested hash representing project hierarchy from actions

data/lib/na/string.rb

@@ -189,7 +189,7 @@ class ::String
   # @param indent [Integer] Number of spaces to indent each line
   # @return [String] Wrapped string
   def wrap(width, indent)
-    return "\n#{self}" if width <= 80
+    return to_s if width.nil? || width <= 0
 
     output = []
     line = []
@@ -310,7 +310,14 @@ class ::String
       m = Regexp.last_match
       t = m['tag']
       d = m['date']
-      future = t =~ /^(done|complete)/ ? false : true
+      # Determine whether to bias toward future or past parsing
+      # Non-done tags usually bias to future, except explicit past phrases like "ago", "yesterday", or "last ..."
+      explicit_past = d =~ /(\bago\b|yesterday|\blast\b)/i
+      future = if t =~ /^(done|complete)/
+                 false
+               else
+                 explicit_past ? false : true
+               end
       parsed_date = d =~ iso_rx ? Time.parse(d) : d.chronify(guess: :begin, future: future)
       parsed_date.nil? ? m[0] : "@#{t}(#{parsed_date.strftime('%F %R')})"
     end

data/lib/na/theme.rb

@@ -57,6 +57,7 @@ module NA
           tags: '{m}',
           value_parens: '{m}',
           values: '{c}',
+          duration: '{y}',
           search_highlight: '{y}',
           note: '{dw}',
           dirname: '{xdw}',

data/lib/na/types.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'na/string'
+
+module NA
+  # Custom types for GLI
+  # Provides natural language date/time and duration parsing
+  # Uses chronify gem for parsing
+  module Types
+    module_function
+
+    # Normalize shorthand relative durations to phrases Chronic can parse.
+    # Examples:
+    #  - "30m ago"    => "30 minutes ago"
+    #  - "-30m"       => "30 minutes ago"
+    #  - "2h30m"      => "2 hours 30 minutes ago" (when default_past)
+    #  - "2h 30m ago" => "2 hours 30 minutes ago"
+    #  - "2:30 ago"   => "2 hours 30 minutes ago"
+    #  - "-2:30"      => "2 hours 30 minutes ago"
+    # Accepts d,h,m units; hours:minutes pattern; optional leading '-'; optional 'ago'.
+    # @param value [String] the duration string to normalize
+    # @param default_past [Boolean] whether to default to past tense
+    # @return [String] the normalized duration string
+    def normalize_relative_duration(value, default_past: false)
+      return value if value.nil?
+
+      s = value.to_s.strip
+      return s if s.empty?
+
+      has_ago = s =~ /\bago\b/i
+      negative = s.start_with?('-')
+
+      text = s.sub(/^[-+]/, '')
+
+      # hours:minutes pattern (e.g., 2:30, 02:30)
+      if (m = text.match(/^(\d{1,2}):(\d{1,2})(?:\s*ago)?$/i))
+        hours = m[1].to_i
+        minutes = m[2].to_i
+        parts = []
+        parts << "#{hours} hours" if hours.positive?
+        parts << "#{minutes} minutes" if minutes.positive?
+        return "#{parts.join(' ')} ago"
+      end
+
+      # Compound d/h/m (order independent, allow spaces): e.g., 1d2h30m, 2h 30m, 30m
+      days = hours = minutes = 0
+      found = false
+      if (dm = text.match(/(?:(\d+)\s*d)/i))
+        days = dm[1].to_i
+        found = true
+      end
+      if (hm = text.match(/(?:(\d+)\s*h)/i))
+        hours = hm[1].to_i
+        found = true
+      end
+      if (mm = text.match(/(?:(\d+)\s*m)/i))
+        minutes = mm[1].to_i
+        found = true
+      end
+
+      if found
+        parts = []
+        parts << "#{days} days" if days.positive?
+        parts << "#{hours} hours" if hours.positive?
+        parts << "#{minutes} minutes" if minutes.positive?
+        # Determine if we should make it past-tense
+        return "#{parts.join(' ')} ago" if negative || has_ago || default_past
+
+        return parts.join(' ')
+
+      end
+
+      # Fall through: not a shorthand we handle
+      s
+    end
+
+    # Parse a natural-language/iso date string for a start time
+    # @param value [String] the date string to parse
+    # @return [Time] the parsed date, or nil if parsing fails
+    def parse_date_begin(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      # Prefer explicit ISO first (only if the value looks ISO-like)
+      iso_rx = /\A\d{4}-\d{2}-\d{2}(?:[ T]\d{1,2}:\d{2}(?::\d{2})?)?\z/
+      if value.to_s.strip =~ iso_rx
+        begin
+          return Time.parse(value)
+        rescue StandardError
+          # fall through to chronify
+        end
+      end
+
+      # Fallback to chronify with guess begin
+      begin
+        # Normalize shorthand (e.g., 2h30m, -2:30, 30m ago)
+        txt = normalize_relative_duration(value.to_s, default_past: true)
+        # Bias to past for expressions like "ago", "yesterday", or "last ..."
+        future = txt !~ /(\bago\b|yesterday|\blast\b)/i
+        result = txt.chronify(guess: :begin, future: future)
+        NA.notify("Parsed '#{value}' as #{result}", debug: true) if result
+        result
+      rescue StandardError
+        nil
+      end
+    end
+
+    # Parse a natural-language/iso date string for an end time
+    # @param value [String] the date string to parse
+    # @return [Time] the parsed date, or nil if parsing fails
+    def parse_date_end(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      # Prefer explicit ISO first (only if the value looks ISO-like)
+      iso_rx = /\A\d{4}-\d{2}-\d{2}(?:[ T]\d{1,2}:\d{2}(?::\d{2})?)?\z/
+      if value.to_s.strip =~ iso_rx
+        begin
+          return Time.parse(value)
+        rescue StandardError
+          # fall through to chronify
+        end
+      end
+
+      # Fallback to chronify with guess end
+      value.to_s.chronify(guess: :end, future: false)
+    end
+
+    # Convert duration expressions to seconds
+    # Supports: "90" (minutes), "45m", "2h", "1d2h30m", with optional leading '-' or trailing 'ago'
+    # Also supports "2:30", "2:30 ago", and word forms like "2 hours 30 minutes (ago)"
+    # @param value [String] the duration string to parse
+    # @return [Integer] the duration in seconds, or nil if parsing fails
+    def parse_duration_seconds(value)
+      return nil if value.nil?
+
+      s = value.to_s.strip
+      return nil if s.empty?
+
+      # Strip leading sign and optional 'ago'
+      s = s.sub(/^[-+]/, '')
+      s = s.sub(/\bago\b/i, '').strip
+
+      # H:MM pattern
+      m = s.match(/^(\d{1,2}):(\d{1,2})$/)
+      if m
+        hours = m[1].to_i
+        minutes = m[2].to_i
+        return (hours * 3600) + (minutes * 60)
+      end
+
+      # d/h/m compact with letters, order independent (e.g., 1d2h30m, 2h 30m, 30m)
+      m = s.match(/^(?:(?<day>\d+)\s*d)?\s*(?:(?<hour>\d+)\s*h)?\s*(?:(?<min>\d+)\s*m)?$/i)
+      if m && !m[0].strip.empty? && (m['day'] || m['hour'] || m['min'])
+        return [[m['day'], 86_400], [m['hour'], 3600], [m['min'], 60]].map { |q, mult| q ? q.to_i * mult : 0 }.sum
+      end
+
+      # Word forms: e.g., "2 hours 30 minutes", "1 day 2 hours", etc.
+      days = 0
+      hours = 0
+      minutes = 0
+      found_word = false
+      if (dm = s.match(/(\d+)\s*(?:day|days)\b/i))
+        days = dm[1].to_i
+        found_word = true
+      end
+      if (hm = s.match(/(\d+)\s*(?:hour|hours|hr|hrs)\b/i))
+        hours = hm[1].to_i
+        found_word = true
+      end
+      if (mm = s.match(/(\d+)\s*(?:minute|minutes|min|mins)\b/i))
+        minutes = mm[1].to_i
+        found_word = true
+      end
+      return (days * 86_400) + (hours * 3600) + (minutes * 60) if found_word
+
+      # Plain number => minutes
+      return s.to_i * 60 if s =~ /^\d+$/
+
+      # Last resort: try chronify two points and take delta
+      begin
+        start = Time.now
+        finish = s.chronify(context: 'now', guess: :end, future: false)
+        return (finish - start).abs.to_i if finish
+      rescue StandardError
+        # ignore
+      end
+
+      nil
+    end
+  end
+end

data/lib/na/version.rb

@@ -5,5 +5,5 @@
 module Na
   ##
   # Current version of the na gem.
-  VERSION = '1.2.86'
+  VERSION = '1.2.87'
 end

data/lib/na.rb

@@ -31,6 +31,7 @@ require 'na/todo'
 require 'na/actions'
 require 'na/project'
 require 'na/action'
+require 'na/types'
 require 'na/editor'
 require 'na/next_action'
 require 'na/prompt'

data/src/_README.md

@@ -9,7 +9,7 @@
 _If you're one of the rare people like me who find this useful, feel free to
 [buy me some coffee][donate]._
 
-The current version of `na` is <!--VER-->1.2.85<!--END VER-->.
+The current version of `na` is <!--VER-->1.2.86<!--END VER-->.
 
 `na` ("next action") is a command line tool designed to make it easy to see what your next actions are for any project, right from the command line. It works with TaskPaper-formatted files (but any plain text format will do), looking for `@na` tags (or whatever you specify) in todo files in your current folder.
 
@@ -235,6 +235,49 @@ See the help output for a list of all available actions.
 @cli(bundle exec bin/na help update)
 ```
 
+#### Time tracking
+
+`na` supports tracking elapsed time between a start and finish for actions using `@started(YYYY-MM-DD HH:MM)` and `@done(YYYY-MM-DD HH:MM)` tags. Durations are not stored; they are calculated on the fly from these tags.
+
+- Add/Finish/Update flags:
+  - `--started TIME` set a start time when creating or finishing an item
+  - `--end TIME` (alias `--finished`) set a done time
+  - `--duration DURATION` backfill start time from the provided end time
+  - All flags accept natural language (via Chronic) and shorthand: `30m ago`, `-2h`, `2h30m`, `2:30 ago`, `yesterday 5pm`
+
+Examples:
+
+```bash
+na add --started "30 minutes ago" "Investigate bug"
+na complete --finished now --duration 2h30m "Investigate bug"
+na update --started "yesterday 3pm" --end "yesterday 5:15pm" "Investigate bug"
+```
+
+- Display flags (next/tagged):
+  - `--times` show per‑action durations and a grand total (implies `--done`)
+  - `--human` format durations as human‑readable text instead of `DD:HH:MM:SS`
+  - `--only_timed` show only actions that have both `@started` and `@done` (implies `--times --done`)
+  - `--only_times` output only the totals section (no action lines; implies `--times --done`)
+  - `--json_times` output a JSON object with timed items, per‑tag totals, and overall total (implies `--times --done`)
+
+Example outputs:
+
+```bash
+# Per‑action durations appended and totals table
+na next --times --human
+
+# Only totals table (Markdown), no action lines
+na tagged "tag*=bug" --only_times
+
+# JSON for scripting
+na next --json_times > times.json
+```
+
+Notes:
+
+- Any newly added or edited action text is scanned for natural‑language values in `@started(...)`/`@done(...)` and normalized to `YYYY‑MM‑DD HH:MM`.
+- The color of durations in output is configurable via the theme key `duration` (defaults to `{y}`).
+
 ##### changelog
 
 View recent changes with `na changelog` or `na changes`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: na
 version: !ruby/object:Gem::Version
-  version: 1.2.86
+  version: 1.2.87
 platform: ruby
 authors:
 - Brett Terpstra
@@ -245,6 +245,7 @@ extra_rdoc_files:
 - README.md
 - na.rdoc
 files:
+- ".cursor/commands/changelog.md"
 - ".cursor/commands/priority35m36m335m32m.md"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
@@ -303,6 +304,7 @@ files:
 - lib/na/string.rb
 - lib/na/theme.rb
 - lib/na/todo.rb
+- lib/na/types.rb
 - lib/na/version.rb
 - na.gemspec
 - na.rdoc