na 1.2.86 → 1.2.88

data/lib/na/string.rb

@@ -189,22 +189,24 @@ 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 = []
-    length = 0
+    # Track visible length of current line (exclude the separating space before first word)
+    length = -1
     text = gsub(/(@\S+)\((.*?)\)/) { "#{Regexp.last_match(1)}(#{Regexp.last_match(2).gsub(/ /, '†')})" }
 
     text.split.each do |word|
       uncolored = NA::Color.uncolor(word)
-      if (length + uncolored.length + 1) <= width
+      candidate = length + 1 + uncolored.length
+      if candidate <= width
         line << word
-        length += uncolored.length + 1
+        length = candidate
       else
         output << line.join(' ')
         line = [word]
-        length = uncolored.length + 1
+        length = uncolored.length
       end
     end
     output << line.join(' ')
@@ -310,7 +312,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.88'
 end

data/lib/na.rb

@@ -31,6 +31,8 @@ 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'
+require 'na/plugins'

data/na/Test.todo.markdown

@@ -0,0 +1,32 @@
+---
+comment: 2023-09-03
+keywords: 
+---
+
+Project3:
+Project0:
+	- This is another task @na
+	- How about this one? @na
+	Subproject:
+		- Bollocks @na
+		Subsub:
+			- Hey, I think it's all working @na
+			- Is this at the end? @na
+	- This better work @na
+2023-09-08:
+	Project2:
+		- new_task @na
+		- new_task @na
+		- test task @na
+	Project0:
+		- other task @na
+		- other task @na
+		- There, that's better @na
+		Subproject:
+			- new_task 2 @na
+			- new_task @na
+			- new_task 2 @na
+	Project1:
+		- Test4
+		- Test5
+		- Test6

data/na/test.md

@@ -0,0 +1,21 @@
+---
+comment: 2023-09-03
+keywords:
+---
+Other New Project:
+	- testing @na @butter
+Brand New Project:
+	- testing @na
+		A multi line (multiline) note
+		with a line break
+	- testing @na
+Project0:
+
+- Test1
+
+- Test2
+
+Project1:
+- Test4
+- Test5
+- Test6

data/na.gemspec

@@ -24,6 +24,7 @@ spec = Gem::Specification.new do |s|
   s.add_development_dependency('minitest', '~> 5.14')
   s.add_development_dependency('rdoc', '~> 4.3')
   s.add_runtime_dependency('chronic', '~> 0.10', '>= 0.10.2')
+  s.add_runtime_dependency('csv', '>= 3.2')
   s.add_runtime_dependency('git', '~> 3.0.0')
   s.add_runtime_dependency('gli','~> 2.21.0')
   s.add_runtime_dependency('mdless', '~> 1.0', '>= 1.0.32')

data/plugins.md

@@ -0,0 +1,38 @@
+I would like to add a plugin architecture to na_gem. It should allow the user to add plugins to ~/.local/share/na/plugins/. These plugins can be any shell script (with a shebang). They can be run with `na plugin NAME`, which accepts the plugin filename with or without an extension, and with or without spaces (so that `plugin AddFoo` will run `Add Foo.sh` if found, but the user can also use `plugin "Add Foo"`).
+
+A plugin will be a shell script that takes input on STDIN. The input should be an action as a JSON object, with the file path, line number, action text, note, and array of tags/values (`tags: [{ name: "done", value: "2025-10-29 03:00"}, { name: "na", value: ""}]`). That should be the default. 
+
+The `plugin` command should accept a `--input TYPE` flag that accepts `json`, `yaml` or `text`. The YAML should be the same as the JSON (but as YAML), and the text should just be the file_path:line_number, action text, and note, split with "||" (newlines in the note replaced with \n, and filename and line number are combined with : not the divider), with no colorization. One action per line. The "||" in `--input text` should also be a flag `--divider "STRING"` that defaults to "||", but allows the user to specify a different string to split the parts on. 
+
+The plugin will need to return output (on STDOUT) in the same format as the input (yaml, json, or text with specified divider), unless `--output FORMAT` is specified with a different type. The `plugin` command will execute the script for every command passed to it, and update the actions based on the returned output.
+
+The `plugin` command should accept all the same filter flags as `finish` or other actions that update commands. 
+
+For the `update` command, it should accept a `--plugin NAME` flag, and if it's using interactive menus, a list of plugin names (basename minus extension) should be added to the list of available operations.
+
+Also add a `--plugin NAME`, `--input TYPE`, and `--output TYPE` flag to all search and display commands (next, grep, tagged, etc.). That way the user can filter output with any command and run the result through the plugin.
+
+In lieu of the `--input` and `--output` commands, the plugin itself can have a comment block after the shebang with `key: value` pairs. When reading a plugin, check for a comment block with `input: JSON` `output: YAML` (case insensitive). The user can also define a `name` or `title` (interchangeable) in this block, which will be used instead of the base name if provided. We need to ignore leading characters when scanning for this comment block (e.g. # or //). The block can have blank lines before it. The only keys we read are input, output, and name/title. Parsing stops at the first blank line or after all three keys are populated. Other keys might exist, like `author` or `description`, which should be ignored.
+
+The plugins shouldn't need to be executable, the hashbang should be read and used to execute the script.
+
+When `na` runs, it should check for the existence of the `plugins` directory, creating it if it's missing, and adding a `~/.local/share/na/plugsin/README.md` file with plugin instructions if one doesn't exist. Any `.md` or `.bak` file in the plugins directory should be ignored. In fact, let's have a helper validate the files in the directory by checking for a shebang and ignoring if none exists, and also ignoring any '.bak' or '.md' files.
+
+Have NA also create 2 sample plugins in the `~/.local/share/na/plugins` folder when creating it (do not create plugins if the folder already exists). Have the sample plugins be a Python script and a Bash script. The sample plugins should just do something benign like add a tag with a dynamic value to the passed actions. In the README.md note that the user can delete the sample plugins. Give the sample plugins names "Add Foo.py" and "Add Bar.sh" and have them add @foo and @bar, respectively.
+
+### Summary ###
+
+- plugins are script files in ~/.local/share/na/plugins
+	- plugins require a shebang, which is used to execute them
+	- plugin base names (without extension) becomes the command name (spaces are handled)
+	- Ignore 
+- `plugin` subcommand
+	- accepts plugin name as argument
+	- has a `--input TYPE` flag that determines the input type (yaml, json, or text)
+	- has a `--output TYPE` (yaml, json, or text)
+	- has a `--divider` flag that determines the divider when `--input text` is used
+- `update` subcommand
+	- accepts a `--plugin NAME` flag
+	- Adds plugin names to interactive menu when no action is specified
+- main script parses the output of the plugin, stripping whitespace and reading it as YAML, JSON, or text split on the divider (based on `--output` and defaulting to the value of `--input`), then updates each action in the result. Line numbers should be passed on both input and output and used to update the specific actions.
+- Generate README and scripts

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.87<!--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`.
@@ -332,6 +375,115 @@ If you're using a single global file, you'll need `--cwd_as` to be `tag` or `pro
 
 After installing a hook, you'll need to close your terminal and start a new session to initialize the new commands.
 
+### Plugins
+
+NA supports a plugin system that allows you to run external scripts to transform or process actions. Plugins are stored in `~/.local/share/na/plugins` and can be written in any language with a shebang.
+
+#### Getting Started
+
+The first time NA runs, it will create the plugins directory with a README and two sample plugins:
+- `Add Foo.py` - Adds a `@foo` tag with a timestamp
+- `Add Bar.sh` - Adds a `@bar` tag
+
+You can delete or modify these sample plugins as needed.
+
+#### Running Plugins
+
+Run a plugin with:
+```bash
+na plugin PLUGIN_NAME
+```
+
+Or use plugins through the `update` command's interactive menu, or pipe actions through plugins on display commands:
+
+```bash
+na update --plugin PLUGIN_NAME           # Run plugin on selected actions
+na next --plugin PLUGIN_NAME             # Transform output only (no file writes)
+na tagged bug --plugin PLUGIN_NAME       # Filter and transform
+na find "search term" --plugin PLUGIN_NAME
+```
+
+#### Plugin Metadata
+
+Plugins can specify their behavior in a metadata block after the shebang:
+
+```bash
+#!/usr/bin/env python3
+# name: My Plugin
+# input: json
+# output: json
+```
+
+Available metadata keys (case-insensitive):
+- `input`: Input format (`json`, `yaml`, `csv`, `text`)
+- `output`: Output format
+- `name` or `title`: Display name (defaults to filename)
+
+#### Input/Output Formats
+
+Plugins accept and return action data. Use `--input` and `--output` flags to override metadata:
+
+```bash
+na plugin MY_PLUGIN --input text --output json --divider "||"
+```
+
+**JSON/YAML Schema:**
+```json
+[
+  {
+    "file_path": "todo.taskpaper",
+    "line": 15,
+    "parents": ["Project", "Subproject"],
+    "text": "- Action text @tag(value)",
+    "note": "Note content",
+    "tags": [
+      { "name": "tag", "value": "value" }
+    ]
+  }
+]
+```
+
+**Text Format:**
+```
+ACTION||ARGS||file_path:line||parents||text||note||tags
+```
+
+Default divider is `||` (configurable with `--divider`).
+- `parents`: `Parent>Child>Leaf`
+- `tags`: `name(value);name;other(value)`
+
+If the first token isn’t a known action, it’s treated as `file_path:line` and the action defaults to UPDATE.
+
+#### Actions
+
+Plugins may return an optional ACTION with arguments. Supported (case-insensitive):
+- UPDATE (default; replace text/note/tags/parents)
+- DELETE
+- COMPLETE/FINISH
+- RESTORE/UNFINISH
+- ARCHIVE
+- ADD_TAG (args: one or more tags)
+- DELETE_TAG/REMOVE_TAG (args: one or more tags)
+- MOVE (args: target project path)
+
+#### Plugin Behavior
+
+**On `update` or `plugin` command:**
+- Plugins can modify text, notes, tags, and parents
+- Changing `parents` will move the action to the new project location
+- `file_path` and `line` cannot be changed
+
+**On display commands (`next`, `tagged`, `find`):**
+- Plugins only transform STDOUT (no file writes)
+- Use returned text/note/tags/parents for rendering
+- Parent changes affect display but not file structure
+
+#### Override Formats
+
+You can override plugin defaults with flags on any command that supports `--plugin`:
+```bash
+na next --plugin FOO --input csv --output text
+```
 
 [fzf]: https://github.com/junegunn/fzf
 [gum]: https://github.com/charmbracelet/gum

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: na
 version: !ruby/object:Gem::Version
-  version: 1.2.86
+  version: 1.2.88
 platform: ruby
 authors:
 - Brett Terpstra
@@ -57,6 +57,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.10.2
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: git
   requirement: !ruby/object:Gem::Requirement
@@ -245,10 +259,12 @@ extra_rdoc_files:
 - README.md
 - na.rdoc
 files:
+- ".cursor/commands/changelog.md"
 - ".cursor/commands/priority35m36m335m32m.md"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - ".travis.yml"
+- 2025-10-29-one-more-na-update.md
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -268,6 +284,7 @@ files:
 - bin/commands/move.rb
 - bin/commands/next.rb
 - bin/commands/open.rb
+- bin/commands/plugin.rb
 - bin/commands/projects.rb
 - bin/commands/prompt.rb
 - bin/commands/restore.rb
@@ -298,14 +315,19 @@ files:
 - lib/na/help_monkey_patch.rb
 - lib/na/next_action.rb
 - lib/na/pager.rb
+- lib/na/plugins.rb
 - lib/na/project.rb
 - lib/na/prompt.rb
 - lib/na/string.rb
 - lib/na/theme.rb
 - lib/na/todo.rb
+- lib/na/types.rb
 - lib/na/version.rb
 - na.gemspec
 - na.rdoc
+- na/Test.todo.markdown
+- na/test.md
+- plugins.md
 - scripts/fixreadme.rb
 - scripts/generate-fish-completions.rb
 - scripts/runtests.sh