na 1.2.87 → 1.2.89

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,50 @@
 _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.86<!--END VER-->.
+The current version of `na` is <!--VER-->1.2.88<!--END VER-->.
+
+<!--GITHUB-->
+### 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)
+<!--END GITHUB--><!--JEKYLL
+- Table of Contents
+{:.toc}
+-->
 
 `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.
 
@@ -140,6 +183,54 @@ To see all next actions across all known todos, use `na next "*"`. You can combi
 @cli(bundle exec bin/na help next)
 ```
 
+##### plugin
+
+Manage and run external plugins. See also the Plugins section below.
+
+```
+@cli(bundle exec bin/na help plugin)
+```
+
+###### plugin new
+
+Create a new plugin script (aliases: `n`). Infers shebang by extension or `--language`.
+
+```
+@cli(bundle exec bin/na help plugin new)
+```
+
+###### plugin edit
+
+Open an existing plugin in your default editor. Prompts if no name is given.
+
+```
+@cli(bundle exec bin/na help plugin edit)
+```
+
+###### plugin run
+
+Run a plugin on selected actions (aliases: `x`). Supports input/output format flags and filters.
+
+```
+@cli(bundle exec bin/na help plugin run)
+```
+
+###### plugin enable
+
+Move a plugin from `plugins_disabled` to `plugins` (alias: `e`).
+
+```
+@cli(bundle exec bin/na help plugin enable)
+```
+
+###### plugin disable
+
+Move a plugin from `plugins` to `plugins_disabled` (alias: `d`).
+
+```
+@cli(bundle exec bin/na help plugin disable)
+```
+
 ##### 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.
@@ -235,49 +326,6 @@ 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`.
@@ -375,6 +423,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: na
 version: !ruby/object:Gem::Version
-  version: 1.2.87
+  version: 1.2.89
 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
@@ -269,6 +283,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
@@ -299,6 +314,7 @@ 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
@@ -308,6 +324,9 @@ files:
 - 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