na 1.2.87 → 1.2.89

data/README.md

@@ -9,7 +9,47 @@
 _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.87.
+The current version of `na` is 1.2.89.
+
+
+### Table of contents
+
+- [Installation](#installation)
+- [Optional Dependencies](#optional-dependencies)
+- [Features](#features)
+  - [Easy matching](#easy-matching)
+  - [Recursion](#recursion)
+  - [Adding todos](#adding-todos)
+  - [Updating todos](#updating-todos)
+- [Terminology](#terminology)
+- [Usage](#usage)
+  - [Commands](#commands)
+  - [add](#add)
+  - [edit](#edit)
+  - [find](#find)
+  - [init, create](#init-create)
+  - [move](#move)
+  - [next, show](#next-show)
+  - [plugin](#plugin)
+  - [projects](#projects)
+  - [saved](#saved)
+  - [scan](#scan)
+  - [tagged](#tagged)
+  - [todos](#todos)
+  - [update](#update)
+  - [changelog](#changelog)
+  - [complete](#complete)
+  - [archive](#archive)
+  - [tag](#tag)
+  - [undo](#undo)
+- [Configuration](#configuration)
+  - [Working with a single global file](#working-with-a-single-global-file)
+  - [Add tasks at the end of a project](#add-tasks-at-the-end-of-a-project)
+  - [Prompt Hooks](#prompt-hooks)
+- [Time tracking](#time-tracking)
+- [Plugins](#plugins)
+- [Changelog](#changelog)
+
 
 `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 +116,7 @@ SYNOPSIS
     na [global options] command [command options] [arguments...]
 
 VERSION
-    1.2.87
+    1.2.89
 
 GLOBAL OPTIONS
     -a, --add               - Add a next action (deprecated, for backwards compatibility)
@@ -112,6 +152,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              - Manage and run plugins
     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
@@ -224,15 +265,19 @@ 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)
@@ -338,12 +383,14 @@ 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
@@ -351,7 +398,9 @@ COMMAND OPTIONS
     --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)
@@ -373,6 +422,121 @@ EXAMPLES
     na next marked
 ```
 
+##### plugin
+
+Manage and run external plugins. See also the Plugins section below.
+
+```
+NAME
+    plugin - Manage and run plugins
+
+SYNOPSIS
+
+    na [global options] plugin [command options] 
+
+    na [global options] plugin [command options] disable NAME
+
+    na [global options] plugin [command options] edit NAME
+
+    na [global options] plugin [command options] enable NAME
+
+    na [global options] plugin [command options] list [--type TYPE|-t TYPE]
+
+    na [global options] plugin [command options] new [--language LANG|--lang LANG] NAME
+
+    na [global options] plugin [command options] run [--divider STRING] [--done] [--file PATH|--in PATH] [--input TYPE] [--output TYPE] [--search QUERY|--find QUERY|--grep QUERY] [--tagged TAG] [-d DEPTH|--depth DEPTH] NAME
+
+COMMAND OPTIONS
+    --[no-]generate-examples - Regenerate sample plugins and README
+
+COMMANDS
+    <default>  - 
+    disable, d - Disable an enabled plugin
+    edit       - Edit an existing plugin
+    enable, e  - Enable a disabled plugin
+    list, ls   - List available plugins
+    new, n     - Create a new plugin
+    run, x     - Run a plugin on selected actions
+```
+
+###### plugin new
+
+Create a new plugin script (aliases: `n`). Infers shebang by extension or `--language`.
+
+```
+NAME
+    new - Create a new plugin
+
+SYNOPSIS
+
+    na [global options] plugin new [command options] NAME
+
+COMMAND OPTIONS
+    --language, --lang=LANG - Language/ext (e.g. rb, py, /usr/bin/env bash) (default: none)
+```
+
+###### plugin edit
+
+Open an existing plugin in your default editor. Prompts if no name is given.
+
+```
+NAME
+    edit - Edit an existing plugin
+
+SYNOPSIS
+
+    na [global options] plugin edit NAME
+```
+
+###### plugin run
+
+Run a plugin on selected actions (aliases: `x`). Supports input/output format flags and filters.
+
+```
+NAME
+    run - Run a plugin on selected actions
+
+SYNOPSIS
+
+    na [global options] plugin run [command options] NAME
+
+COMMAND OPTIONS
+    -d, --depth=DEPTH              - Search for files X directories deep (default: 1)
+    --divider=STRING               - Text divider when using --input/--output text (default: none)
+    --[no-]done                    - Include @done actions
+    --file, --in=PATH              - Specify the file to search for the task (default: none)
+    --input=TYPE                   - Input format (json|yaml|csv|text) (default: none)
+    --output=TYPE                  - Output format (json|yaml|csv|text) (default: none)
+    --search, --find, --grep=QUERY - Filter results using search terms (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)
+```
+
+###### plugin enable
+
+Move a plugin from `plugins_disabled` to `plugins` (alias: `e`).
+
+```
+NAME
+    enable - Enable a disabled plugin
+
+SYNOPSIS
+
+    na [global options] plugin enable NAME
+```
+
+###### plugin disable
+
+Move a plugin from `plugins` to `plugins_disabled` (alias: `d`).
+
+```
+NAME
+    disable - Disable an enabled plugin
+
+SYNOPSIS
+
+    na [global options] plugin disable NAME
+```
+
 ##### projects
 
 List all projects in a file. If arguments are provided, they're used to match a todo file from history, otherwise the todo file(s) in the current directory will be used.
@@ -499,10 +663,12 @@ 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
@@ -511,6 +677,8 @@ COMMAND OPTIONS
     --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)
@@ -609,6 +777,7 @@ 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
@@ -617,9 +786,12 @@ COMMAND OPTIONS
     -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)
@@ -644,49 +816,6 @@ 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`.
@@ -898,6 +1027,154 @@ 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.
 
+### 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}`).
+
+### 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
+
+You can manage and run plugins using subcommands under `na plugin`:
+
+- `new`/`n`: scaffold a new plugin script
+- `edit`: open an existing plugin
+- `run`/`x`: run a plugin against selected actions
+- `enable`/`e`: move from disabled to enabled
+- `disable`/`d`: move from enabled to disabled
+
+Plugins are executed with actions on STDIN and must return actions on STDOUT. Display commands can still pipe through plugins via `--plugin`, which only affects STDOUT (no writes).
+
+#### 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/bin/commands/find.rb

@@ -68,6 +68,22 @@ class App
     c.desc "Output actions nested by file and project"
     c.switch %[omnifocus], negatable: false
 
+    c.desc 'Run a plugin on results (STDOUT only; no file writes)'
+    c.arg_name 'NAME'
+    c.flag %i[plugin]
+
+    c.desc 'Plugin input format (json|yaml|csv|text)'
+    c.arg_name 'TYPE'
+    c.flag %i[input]
+
+    c.desc 'Plugin output format (json|yaml|csv|text)'
+    c.arg_name 'TYPE'
+    c.flag %i[output]
+
+    c.desc 'Divider string for text IO'
+    c.arg_name 'STRING'
+    c.flag %i[divider]
+
     c.action do |global_options, options, args|
       options[:nest] = true if options[:omnifocus]
 
@@ -175,6 +191,52 @@ class App
           [tokens]
         end
 
+      # Plugin piping (display-only)
+      if options[:plugin]
+        NA::Plugins.ensure_plugins_home
+        plugin_path = options[:plugin]
+        unless File.exist?(plugin_path)
+          resolved = NA::Plugins.resolve_plugin(plugin_path)
+          plugin_path = resolved if resolved
+        end
+        if plugin_path && File.exist?(plugin_path)
+          meta = NA::Plugins.parse_plugin_metadata(plugin_path)
+          input_fmt = (options[:input] || meta['input'] || 'json').to_s
+          output_fmt = (options[:output] || meta['output'] || input_fmt).to_s
+          divider = (options[:divider] || '||')
+
+          io_actions = todo.actions.map(&:to_plugin_io_hash)
+          stdin_str = NA::Plugins.serialize_actions(io_actions, format: input_fmt, divider: divider)
+          stdout = NA::Plugins.run_plugin(plugin_path, stdin_str)
+          returned = Array(NA::Plugins.parse_actions(stdout, format: output_fmt, divider: divider))
+          index = {}
+          todo.actions.each { |a| index["#{a.file_path}:#{a.file_line}"] = a }
+          returned.each do |h|
+            key = "#{h['file_path']}:#{h['line'].to_i}"
+            a = index[key]
+            next unless a
+            new_text = h['text'].to_s
+            new_note = h['note'].to_s
+            new_tags = Array(h['tags']).map { |t| [t['name'].to_s, t['value'].to_s] }
+            new_text = new_text.gsub(/(?<=\A| )@\S+(?:\(.*?\))?/, '')
+            unless new_tags.empty?
+              tag_str = new_tags.map { |k, v| v.to_s.empty? ? "@#{k}" : "@#{k}(#{v})" }.join(' ')
+              new_text = new_text.strip + (tag_str.empty? ? '' : " #{tag_str}")
+            end
+            a.action = new_text
+            a.note = new_note.empty? ? [] : new_note.split("\n")
+            a.instance_variable_set(:@tags, a.scan_tags)
+            parents = Array(h['parents']).map(&:to_s)
+            if parents.any?
+              new_proj = parents.first.to_s
+              new_chain = parents[1..] || []
+              a.instance_variable_set(:@project, new_proj)
+              a.parent = new_chain
+            end
+          end
+        end
+      end
+
       todo.actions.output(depth,
                           { files: todo.files,
                             regexes: regexes,

data/bin/commands/next.rb

@@ -83,6 +83,22 @@ class App
     c.desc "Include @done actions"
     c.switch %i[done]
 
+    c.desc "Run a plugin on results (STDOUT only; no file writes)"
+    c.arg_name 'NAME'
+    c.flag %i[plugin]
+
+    c.desc 'Plugin input format (json|yaml|csv|text)'
+    c.arg_name 'TYPE'
+    c.flag %i[input]
+
+    c.desc 'Plugin output format (json|yaml|csv|text)'
+    c.arg_name 'TYPE'
+    c.flag %i[output]
+
+    c.desc 'Divider string for text IO'
+    c.arg_name 'STRING'
+    c.flag %i[divider]
+
     c.desc "Output actions nested by file"
     c.switch %i[nest], negatable: false
 
@@ -262,6 +278,55 @@ class App
                   Run `na todos` to see available todo files.")
       end
       NA::Pager.paginate = false if options[:omnifocus]
+
+      # If a plugin is specified, transform actions in memory for display only
+      if options[:plugin]
+        NA::Plugins.ensure_plugins_home
+        plugin_path = options[:plugin]
+        unless File.exist?(plugin_path)
+          resolved = NA::Plugins.resolve_plugin(plugin_path)
+          plugin_path = resolved if resolved
+        end
+        if plugin_path && File.exist?(plugin_path)
+          meta = NA::Plugins.parse_plugin_metadata(plugin_path)
+          input_fmt = (options[:input] || meta['input'] || 'json').to_s
+          output_fmt = (options[:output] || meta['output'] || input_fmt).to_s
+          divider = (options[:divider] || '||')
+
+          io_actions = todo.actions.map(&:to_plugin_io_hash)
+          stdin_str = NA::Plugins.serialize_actions(io_actions, format: input_fmt, divider: divider)
+          stdout = NA::Plugins.run_plugin(plugin_path, stdin_str)
+          returned = Array(NA::Plugins.parse_actions(stdout, format: output_fmt, divider: divider))
+          index = {}
+          todo.actions.each { |a| index["#{a.file_path}:#{a.file_line}"] = a }
+          returned.each do |h|
+            key = "#{h['file_path']}:#{h['line'].to_i}"
+            a = index[key]
+            next unless a
+            # Update for display: text, note, tags
+            new_text = h['text'].to_s
+            new_note = h['note'].to_s
+            new_tags = Array(h['tags']).map { |t| [t['name'].to_s, t['value'].to_s] }
+            # replace tags in text
+            new_text = new_text.gsub(/(?<=\A| )@\S+(?:\(.*?\))?/, '')
+            unless new_tags.empty?
+              tag_str = new_tags.map { |k, v| v.to_s.empty? ? "@#{k}" : "@#{k}(#{v})" }.join(' ')
+              new_text = new_text.strip + (tag_str.empty? ? '' : " #{tag_str}")
+            end
+            a.action = new_text
+            a.note = new_note.empty? ? [] : new_note.split("\n")
+            a.instance_variable_set(:@tags, a.scan_tags)
+            # parents -> possibly change project and parent chain for display
+            parents = Array(h['parents']).map(&:to_s)
+            if parents.any?
+              new_proj = parents.first.to_s
+              new_chain = parents[1..] || []
+              a.instance_variable_set(:@project, new_proj)
+              a.parent = new_chain
+            end
+          end
+        end
+      end
       todo.actions.output(depth,
                           { files: todo.files,
                             nest: options[:nest],