na 1.2.86 → 1.2.88

data/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 1.2.86.
+The current version of `na` is 1.2.88.
 
 `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.
 
@@ -76,7 +76,7 @@ SYNOPSIS
     na [global options] command [command options] [arguments...]
 
 VERSION
-    1.2.86
+    1.2.88
 
 GLOBAL OPTIONS
     -a, --add               - Add a next action (deprecated, for backwards compatibility)
@@ -112,6 +112,7 @@ COMMANDS
     move                - Move an existing action to a different section
     next, show          - Show next actions
     open                - Open a todo file in the default editor
+    plugin              - Run a plugin on selected actions
     projects            - Show list of projects for a file
     prompt              - Show or install prompt hooks for the current shell
     restore, unfinish   - Find and remove @done tag from an action
@@ -152,11 +153,14 @@ DESCRIPTION
 COMMAND OPTIONS
     --at=POSITION                   - Add task at [s]tart or [e]nd of target project (default: none)
     -d, --depth=DEPTH               - Search for files X directories deep (default: 1)
+    --duration=DURATION             - Duration (e.g. 45m, 2h, 1d2h30m, or minutes) (default: none)
+    --end, --finished=DATE          - End/Finished time (natural language or ISO) (default: none)
     -f, --file=PATH                 - Specify the file to which the task should be added (default: none)
     --finish, --done                - Mark task as @done with date
     --in, --todo=TODO_FILE          - Add to a known todo file, partial matches allowed (default: none)
     -n, --note                      - Prompt for additional notes. STDIN input (piped) will be treated as a note if present.
     -p, --priority=PRIO             - Add a priority level 1-5 or h, m, l (default: 0)
+    --started=DATE                  - Started time (natural language or ISO) (default: none)
     -t, --tag=TAG                   - Use a tag other than the default next action tag (default: none)
     --to, --project, --proj=PROJECT - Add action to specific project (default: Inbox)
     -x                              - Don't add next action tag to new entry
@@ -221,18 +225,24 @@ DESCRIPTION
 
 COMMAND OPTIONS
     -d, --depth=DEPTH                      - Recurse to depth (default: none)
+    --divider=STRING                       - Divider string for text IO (default: none)
     --[no-]done                            - Include @done actions
     -e, --regex                            - Interpret search pattern as regular expression
+    --human                                - Format durations in human-friendly form
     --in=TODO_PATH                         - Show actions from a specific todo file in history. May use wildcards (* and ?) (default: none)
+    --input=TYPE                           - Plugin input format (json|yaml|csv|text) (default: none)
     --nest                                 - Output actions nested by file
     --no_file                              - No filename in output
     --[no-]notes                           - Include notes in output
     -o, --or                               - Combine search tokens with OR, displaying actions matching ANY of the terms
     --omnifocus                            - Output actions nested by file and project
+    --output=TYPE                          - Plugin output format (json|yaml|csv|text) (default: none)
+    --plugin=NAME                          - Run a plugin on results (STDOUT only; no file writes) (default: none)
     --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
     --save=TITLE                           - Save this search for future use (default: none)
     --[no-]search_notes                    - Include notes in search (default: enabled)
     --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
+    --times                                - Show per-action durations and total
     -v, --invert                           - Show actions not matching search pattern
     -x, --exact                            - Match pattern exactly
 
@@ -333,16 +343,24 @@ DESCRIPTION
 COMMAND OPTIONS
     --all                                  - Show next actions from all known todo files (in any directory)
     -d, --depth=DEPTH                      - Recurse to depth (default: none)
+    --divider=STRING                       - Divider string for text IO (default: none)
     --[no-]done                            - Include @done actions
     --exact                                - Search query is exact text match (not tokens)
     --file=TODO_FILE                       - Display matches from specific todo file ([relative] path) (default: none)
     --hidden                               - Include hidden directories while traversing
+    --human                                - Format durations in human-friendly form
     --in, --todo=TODO                      - Display matches from a known todo file anywhere in history (short name) (may be used more than once, default: none)
+    --input=TYPE                           - Plugin input format (json|yaml|csv|text) (default: none)
+    --json_times                           - Output times as JSON object (implies --times and --done)
     --nest                                 - Output actions nested by file
     --no_file                              - No filename in output
     --[no-]notes                           - Include notes in output
     --omnifocus                            - Output actions nested by file and project
+    --only_timed                           - Show only actions that have a duration (@started and @done)
+    --only_times                           - Output only elapsed time totals (implies --times and --done)
+    --output=TYPE                          - Plugin output format (json|yaml|csv|text) (default: none)
     -p, --prio, --priority=PRIORITY        - Match actions with priority, allows <>= comparison (may be used more than once, default: none)
+    --plugin=NAME                          - Run a plugin on results (STDOUT only; no file writes) (default: none)
     --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
     --regex                                - Search query is regular expression
     --save=TITLE                           - Save this search for future use (default: none)
@@ -350,6 +368,7 @@ COMMAND OPTIONS
     --[no-]search_notes                    - Include notes in search (default: enabled)
     -t, --tag=TAG                          - Alternate tag to search for (default: none)
     --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
+    --times                                - Show per-action durations and total
 
 EXAMPLES
 
@@ -489,19 +508,28 @@ DESCRIPTION
 
 COMMAND OPTIONS
     -d, --depth=DEPTH                      - Recurse to depth (default: 1)
+    --divider=STRING                       - Divider string for text IO (default: none)
     --[no-]done                            - Include @done actions
     --exact                                - Search query is exact text match (not tokens)
+    --human                                - Format durations in human-friendly form
     --in=TODO_PATH                         - Show actions from a specific todo file in history. May use wildcards (* and ?) (default: none)
+    --input=TYPE                           - Plugin input format (json|yaml|csv|text) (default: none)
+    --json_times                           - Output times as JSON object (implies --times and --done)
     --nest                                 - Output actions nested by file
     --no_file                              - No filename in output
     --[no-]notes                           - Include notes in output
     -o, --or                               - Combine tags with OR, displaying actions matching ANY of the tags
     --omnifocus                            - Output actions nested by file and project
+    --only_timed                           - Show only actions that have a duration (@started and @done)
+    --only_times                           - Output only elapsed time totals (implies --times and --done)
+    --output=TYPE                          - Plugin output format (json|yaml|csv|text) (default: none)
+    --plugin=NAME                          - Run a plugin on results (STDOUT only; no file writes) (default: none)
     --proj, --project=PROJECT[/SUBPROJECT] - Show actions from a specific project (default: none)
     --regex                                - Search query is regular expression
     --save=TITLE                           - Save this search for future use (default: none)
     --search, --find, --grep=QUERY         - Filter results using search terms (may be used more than once, default: none)
     --[no-]search_notes                    - Include notes in search (default: enabled)
+    --times                                - Show per-action durations and total
     -v, --invert                           - Show actions not matching tags
 
 EXAMPLES
@@ -594,21 +622,28 @@ COMMAND OPTIONS
     --at=POSITION                          - When moving task, add at [s]tart or [e]nd of target project (default: none)
     -d, --depth=DEPTH                      - Search for files X directories deep (default: 1)
     --delete                               - Delete an action
+    --divider=STRING                       - Divider string for text IO (default: none)
     --[no-]done                            - Include @done actions
+    --duration=DURATION                    - Duration (e.g. 45m, 2h, 1d2h30m, or minutes) (default: none)
     -e, --regex                            - Interpret search pattern as regular expression
     --edit                                 - Open action in editor (vim).             Natural language dates will be parsed and converted in date-based tags.
+    --end, --finished=DATE                 - End/Finished time (natural language or ISO) (default: none)
     -f, --finish                           - Add a @done tag to action
     --file=PATH                            - Specify the file to search for the task (default: none)
     --in, --todo=TODO_FILE                 - Use a known todo file, partial matches allowed (default: none)
+    --input=TYPE                           - Plugin input format (json|yaml|csv|text) (default: none)
     -n, --note                             - Prompt for additional notes. Input will be appended to any existing note.     If STDIN input (piped) is detected, it will be used as a note.
     -o, --overwrite                        - Overwrite note instead of appending
+    --output=TYPE                          - Plugin output format (json|yaml|csv|text) (default: none)
     -p, --priority=PRIO                    - Add/change a priority level 1-5 (default: 0)
+    --plugin=NAME                          - Run a plugin by name on selected actions (default: none)
     --proj, --project=PROJECT[/SUBPROJECT] - Affect actions from a specific project (default: none)
     -r, --remove=TAG                       - Remove a tag from the action, use multiple times or combine multiple tags with a comma,             wildcards (* and ?) allowed (may be used more than once, default: none)
     --replace=TEXT                         - Use with --find to find and replace with new text. Enables --exact when used (default: none)
     --restore                              - Remove @done tag from action
     --search, --find, --grep=QUERY         - Filter results using search terms (may be used more than once, default: none)
     --[no-]search_notes                    - Include notes in search (default: enabled)
+    --started=DATE                         - Started time (natural language or ISO) (default: none)
     -t, --tag=TAG                          - Add a tag to the action, @tag(values) allowed, use multiple times or combine multiple tags with a comma (may be used more than once, default: none)
     --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
     --to, --move=PROJECT                   - Move action to specific project (default: none)
@@ -626,6 +661,49 @@ EXAMPLES
     na update --archive My cool action
 ```
 
+#### 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`.
@@ -655,7 +733,9 @@ COMMAND OPTIONS
     -a, --archive                          - Add a @done tag to action and move to Archive
     --all                                  - Act on all matches immediately (no menu)
     -d, --depth=DEPTH                      - Search for files X directories deep (default: 1)
+    --duration=DURATION                    - Duration (e.g. 45m, 2h, 1d2h30m, or minutes) (default: none)
     -e, --regex                            - Interpret search pattern as regular expression
+    --end, --finished=DATE                 - End/Finished time (natural language or ISO) (default: none)
     --file=PATH                            - Specify the file to search for the task (default: none)
     --in, --todo=TODO_FILE                 - Use a known todo file, partial matches allowed (default: none)
     -n, --note                             - Prompt for additional notes. Input will be appended to any existing note.     If STDIN input (piped) is detected, it will be used as a note.
@@ -663,6 +743,7 @@ COMMAND OPTIONS
     --proj, --project=PROJECT[/SUBPROJECT] - Affect actions from a specific project (default: none)
     --search, --find, --grep=QUERY         - Filter results using search terms (may be used more than once, default: none)
     --[no-]search_notes                    - Include notes in search (default: enabled)
+    --started=DATE                         - Started time (natural language or ISO) (default: none)
     --tagged=TAG                           - Match actions containing tag. Allows value comparisons (may be used more than once, default: none)
     --to, --move=PROJECT                   - Add a @done tag and move action to specific project (default: none)
     -x, --exact                            - Match pattern exactly
@@ -834,6 +915,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

data/Rakefile

@@ -1,70 +1,70 @@
-require "rake/clean"
-require "rubygems"
-require "rubygems/package_task"
-require "rdoc/task"
-require "bump/tasks"
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "rubocop/rake_task"
-require "yard"
-require "tty-spinner"
-require "English"
+require 'rake/clean'
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rdoc/task'
+require 'bump/tasks'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'yard'
+require 'tty-spinner'
+require 'English'
 
 YARD::Rake::YardocTask.new do |t|
-  t.files = ["lib/na/*.rb"]
-  t.options = ["--markup-provider=redcarpet", "--markup=markdown", "--no-private", "-p", "yard_templates"]
-  t.stats_options = ["--list-undoc"] # Uncommented this line for stats options
+  t.files = ['lib/na/*.rb']
+  t.options = ['--markup-provider=redcarpet', '--markup=markdown', '--no-private', '-p', 'yard_templates']
+  t.stats_options = ['--list-undoc'] # Uncommented this line for stats options
 end
 
 ## Docker error class
 class DockerError < StandardError
   def initialize(msg = nil)
-    msg = msg ? "Docker error: #{msg}" : "Docker error"
-    super(msg)
+    msg = msg ? "Docker error: #{msg}" : 'Docker error'
+    super
   end
 end
 
 task default: %i[test yard]
 
-desc "Run test suite"
+desc 'Run test suite'
 task test: %i[rubocop spec]
 
 RSpec::Core::RakeTask.new do |t|
-  t.rspec_opts = "--format documentation"
+  t.rspec_opts = '--format documentation'
 end
 
 RuboCop::RakeTask.new do |t|
-  t.formatters = ["progress"]
+  t.formatters = ['progress']
 end
 
 task :doc, [*Rake.application[:yard].arg_names] => [:yard]
 
 Rake::RDocTask.new do |rd|
-  rd.main = "README.rdoc"
-  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb", "bin/**/*")
-  rd.title = "na"
+  rd.main = 'README.rdoc'
+  rd.rdoc_files.include('README.rdoc', 'lib/**/*.rb', 'bin/**/*')
+  rd.title = 'na'
 end
 
-spec = eval(File.read("na.gemspec"))
+spec = eval(File.read('na.gemspec'))
 
 Gem::PackageTask.new(spec) do |pkg|
 end
-require "rake/testtask"
+require 'rake/testtask'
 Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.test_files = FileList["test/*_test.rb"]
+  t.libs << 'test'
+  t.test_files = FileList['test/*_test.rb']
 end
 
-desc "Install current gem in all versions of asdf-controlled ruby"
+desc 'Install current gem in all versions of asdf-controlled ruby'
 task :install do
-  Rake::Task["clobber"].invoke
-  Rake::Task["package"].invoke
-  Dir.chdir "pkg"
-  file = Dir.glob("*.gem").last
+  Rake::Task['clobber'].invoke
+  Rake::Task['package'].invoke
+  Dir.chdir 'pkg'
+  file = Dir.glob('*.gem').last
 
   current_ruby = `asdf current ruby`.match(/(\d.\d+.\d+)/)[1]
 
-  `asdf list ruby`.split.map { |ruby| ruby.strip.sub(/^*/, "") }.each do |ruby|
+  `asdf list ruby`.split.map { |ruby| ruby.strip.sub(/^*/, '') }.each do |ruby|
     `asdf shell ruby #{ruby}`
     puts `gem install #{file}`
   end
@@ -72,10 +72,10 @@ task :install do
   `asdf shell ruby #{current_ruby}`
 end
 
-desc "Development version check"
+desc 'Development version check'
 task :ver do
   gver = `git ver`
-  cver = IO.read(File.join(File.dirname(__FILE__), "CHANGELOG.md")).match(/^#+ (\d+\.\d+\.\d+(\w+)?)/)[1]
+  cver = IO.read(File.join(File.dirname(__FILE__), 'CHANGELOG.md')).match(/^#+ (\d+\.\d+\.\d+(\w+)?)/)[1]
   res = `grep VERSION lib/na/version.rb`
   version = res.match(/VERSION *= *['"](\d+\.\d+\.\d+(\w+)?)/)[1]
   puts "git tag: #{gver}"
@@ -83,22 +83,22 @@ task :ver do
   puts "changelog: #{cver}"
 end
 
-desc "Changelog version check"
+desc 'Changelog version check'
 task :cver do
-  puts IO.read(File.join(File.dirname(__FILE__), "CHANGELOG.md")).match(/^#+ (\d+\.\d+\.\d+(\w+)?)/)[1]
+  puts IO.read(File.join(File.dirname(__FILE__), 'CHANGELOG.md')).match(/^#+ (\d+\.\d+\.\d+(\w+)?)/)[1]
 end
 
-desc "Bump incremental version number"
+desc 'Bump incremental version number'
 task :bump, :type do |_, args|
-  args.with_defaults(type: "inc")
-  version_file = "lib/na/version.rb"
+  args.with_defaults(type: 'inc')
+  version_file = 'lib/na/version.rb'
   content = IO.read(version_file)
   content.sub!(/VERSION = '(?<major>\d+)\.(?<minor>\d+)\.(?<inc>\d+)(?<pre>\S+)?'/) do
     m = Regexp.last_match
-    major = m["major"].to_i
-    minor = m["minor"].to_i
-    inc = m["inc"].to_i
-    pre = m["pre"]
+    major = m['major'].to_i
+    minor = m['minor'].to_i
+    inc = m['inc'].to_i
+    pre = m['pre']
 
     case args[:type]
     when /^maj/
@@ -115,73 +115,73 @@ task :bump, :type do |_, args|
     $stdout.puts "At version #{major}.#{minor}.#{inc}#{pre}"
     "VERSION = '#{major}.#{minor}.#{inc}#{pre}'"
   end
-  File.open(version_file, "w+") { |f| f.puts content }
+  File.open(version_file, 'w+') { |f| f.puts content }
 end
 
 # task default: %i[test clobber package]
 
-desc "Remove packages"
+desc 'Remove packages'
 task :clobber_packages do
-  FileUtils.rm_f "pkg/*"
+  FileUtils.rm_f 'pkg/*'
 end
 # Make a prerequisite of the preexisting clobber task
-desc "Clobber files"
+desc 'Clobber files'
 task clobber: :clobber_packages
 
-desc "Get Script Version"
+desc 'Get Script Version'
 task :sver do
   res = `grep VERSION lib/na/version.rb`
   version = res.match(/VERSION *= *['"](\d+\.\d+\.\d+(\w+)?)/)[1]
   print version
 end
 
-desc "Run tests in Docker"
+desc 'Run tests in Docker'
 task :dockertest, :version, :login, :attempt do |_, args|
-  args.with_defaults(version: "all", login: false, attempt: 1)
+  args.with_defaults(version: 'all', login: false, attempt: 1)
   `open -a Docker`
 
-  Rake::Task["clobber"].reenable
-  Rake::Task["clobber"].invoke
-  Rake::Task["build"].reenable
-  Rake::Task["build"].invoke
+  Rake::Task['clobber'].reenable
+  Rake::Task['clobber'].invoke
+  Rake::Task['build'].reenable
+  Rake::Task['build'].invoke
 
   case args[:version]
   when /^a/
     %w[6 7 3].each do |v|
-      Rake::Task["dockertest"].reenable
-      Rake::Task["dockertest"].invoke(v, false)
+      Rake::Task['dockertest'].reenable
+      Rake::Task['dockertest'].invoke(v, false)
     end
     Process.exit 0
   when /^3\.?3/
-    img = "natest33"
-    file = "docker/Dockerfile-3.3"
+    img = 'natest33'
+    file = 'docker/Dockerfile-3.3'
   when /^3/
-    version = "3.0"
-    img = "natest3"
-    file = "docker/Dockerfile-3.0"
+    version = '3.0'
+    img = 'natest3'
+    file = 'docker/Dockerfile-3.0'
   when /6$/
-    version = "2.6"
-    img = "natest26"
-    file = "docker/Dockerfile-2.6"
+    version = '2.6'
+    img = 'natest26'
+    file = 'docker/Dockerfile-2.6'
   when /(^2|7$)/
-    version = "2.7"
-    img = "natest27"
-    file = "docker/Dockerfile-2.7"
+    version = '2.7'
+    img = 'natest27'
+    file = 'docker/Dockerfile-2.7'
   else
-    version = "3.0.1"
-    img = "natest"
-    file = "docker/Dockerfile"
+    version = '3.0.1'
+    img = 'natest'
+    file = 'docker/Dockerfile'
   end
 
   puts `docker build . --file #{file} -t #{img}`
 
-  raise DockerError, "Error building docker image" unless $CHILD_STATUS.success?
+  raise DockerError, 'Error building docker image' unless $CHILD_STATUS.success?
 
   dirs = {
-    File.dirname(__FILE__) => "/na",
-    File.expand_path("~/.config") => "/root/.config"
+    File.dirname(__FILE__) => '/na',
+    File.expand_path('~/.config') => '/root/.config'
   }
-  dir_args = dirs.map { |s, d| " -v '#{s}:#{d}'" }.join(" ")
+  dir_args = dirs.map { |s, d| " -v '#{s}:#{d}'" }.join(' ')
   exec "docker run #{dir_args} -it #{img} /bin/bash -l" if args[:login]
 
   spinner = TTY::Spinner.new("[:spinner] Running tests (#{version})...", hide_cursor: true)
@@ -197,15 +197,15 @@ task :dockertest, :version, :login, :attempt do |_, args|
   # puts res
   # puts commit&.empty? ? "Error commiting Docker tag #{img}" : "Committed Docker tag #{img}"
 rescue DockerError
-  raise StandardError.new("Docker not responding") if args[:attempt] > 3
+  raise StandardError.new('Docker not responding') if args[:attempt] > 3
 
   `open -a Docker`
   sleep 3
-  Rake::Task["dockertest"].reenable
-  Rake::Task["dockertest"].invoke(args[:version], args[:login], args[:attempt] + 1)
+  Rake::Task['dockertest'].reenable
+  Rake::Task['dockertest'].invoke(args[:version], args[:login], args[:attempt] + 1)
 end
 
-desc "alias for build"
+desc 'alias for build'
 task package: :build
 
 desc 'Run tests with coverage'

data/bin/commands/add.rb

@@ -11,6 +11,17 @@ class App
   allow you to pick to which file the action gets added.'
   arg_name "ACTION"
   command :add do |c|
+    c.desc "Started time (natural language or ISO)"
+    c.arg_name "DATE"
+    c.flag %i[started], type: :date_begin
+
+    c.desc "End/Finished time (natural language or ISO)"
+    c.arg_name "DATE"
+    c.flag %i[end finished], type: :date_end
+
+    c.desc "Duration (e.g. 45m, 2h, 1d2h30m, or minutes)"
+    c.arg_name "DURATION"
+    c.flag %i[duration], type: :duration
     c.example 'na add "A cool feature I thought of @idea"', desc: "Add a new action to the Inbox, including a tag"
     c.example 'na add "A bug I need to fix" -p 4 -n',
               desc: "Add a new action to the Inbox, set its @priority to 4, and prompt for an additional note."
@@ -181,7 +192,26 @@ class App
       note.<< split_note unless split_note.nil?
       note.concat(line_note) unless line_note.nil?
 
-      NA.add_action(target, options[:project], action, note, finish: options[:finish], append: append)
+      # Compute started/done based on flags
+      started_at = options[:started]
+      started_at = NA::Types.parse_date_begin(started_at) if started_at && !started_at.is_a?(Time)
+      done_at = options[:end] || options[:finished]
+      done_at = NA::Types.parse_date_end(done_at) if done_at && !done_at.is_a?(Time)
+      duration_seconds = options[:duration]
+
+      NA.notify("ADD parsed started_at=#{started_at.inspect} done_at=#{done_at.inspect} duration=#{duration_seconds.inspect}", debug: true)
+
+      # Ensure @started is present in the action text if a start time was provided
+      if started_at
+        started_str = started_at.strftime('%Y-%m-%d %H:%M')
+        # remove any existing @start/@started tag before appending
+        action = action.gsub(/(?<=\A| )@start(?:ed)?\(.*?\)/i, '').strip
+        action = "#{action} @started(#{started_str})"
+      end
+
+      NA.add_action(target, options[:project], action, note,
+                    finish: options[:finish], append: append,
+                    started_at: started_at, done_at: done_at, duration_seconds: duration_seconds)
     end
   end
 end

data/bin/commands/changes.rb

@@ -9,6 +9,7 @@ class App
       pagers = [
         'mdless',
         'mdcat',
+        'glow',
         'bat',
         ENV['PAGER'],
         'less -FXr',