v2.0 breaking changes refactor (#448)

* fix: some improvements to run_in_cwd and run_in_fullscreen_win

* refactor!: remove toggleterm and terminal strategies

* refactor!: drop support for older Neovim versions

* tools: improve makefile

* refactor!: simplify logging utility and configuration

* refactor: vim.loop -> vim.uv

* doc: add some type annotations

* cleanup: unused strategy code

* refactor: simplify setup logic

* refactor!: convert OverseerInfo to checkhealth

* refactor!: get rid of task priority

* refactor: simplify make task generator

* refactor: simplify parameter prompt logic by removing behaviors

* refactor: allow error reporting in template generator

* refactor: simplify templates

* refactor!: get rid of shell template

* refactor: rearrange component type definition

* refactor!: remove files.join -> vim.fs.joinpath

* refactor: move vscode utilities out of template/ dir

* refactor: split vscode template logic from utility code

* refactor!: task bundles get the axe

* refactor!: remove OverseerBuild command

* cleanup!: remove callback from condition checks

* refactor: automatic template loading; remove options

* refactor!: remove auto-require behavior from top-level overseer module

* cleanup: remove deprecated method

* cleanup: remove some deprecated method handling

* refactor!: rename run_template -> run_task

* feat: run_task can pass a callback for post-build pre-create

* refactor: remove preload_components option

* refactor: dynamically find components using runtimepath

* doc: update a bunch of docs for the recent changes

* perf: make first require(config) faster

* refactor!: delete overseer.wrap_template

* cleanup: get rid of telescope-specific picker logic

* refactor: use virtual text for form labels

* refactor: use inline virtual text for forms and task editor

* feat: restore template_dirs config option

* refactor!: rewrite task list rendering to be function-based

* fix: eliminate all deprecation warnings

* cleanup!: remove some options for list_tasks that are unnecessary

* feat: configurable task sorting

* fix: hide deprecated components in task editor

* fix: error in condition filetype handling

* refactor: mark some methods on task as private

* refactor!: remove OverseerClearCache command

* feat: do not require calling setup()

* fix: undo in task editor no longer borks everything

* fix: task editor can change component param values

* feat: OverseerShell command and overseer.run_cmd method

* refactor!: replace behavior tree parsing with functions

* refactor!: remove config and custom keymaps for form and task editor windows

* doc: remove entreaty to request task system support

* feat: can hook builtin vim.system and vim.fn.jobstart

* doc: vim.diagnostics -> vim.diagnostic

* doc: replaced :OverseerInfo with :checkhealth overseer

* doc: small corrections

* feat: add component alias for wrapped tasks

* fix: starting a task doesn't switch to normal mode

* feat: condition callback for hooking builtins

* feat: unique component has 'soft' option

* refactor!: rename time options to denote units

* fix: guard against cursor outside window

* fix: run_in_fullscreen_win uses new buffer by default

* refactor: rename hook_builtins -> wrap_builtins

* fix: attach source to wrapped tasks and filter them out of task list by default

* fix: neotest strategy

* fix: disable builtin wrapping when in fast event

* refactor: clean up actions and lazy load

* refactor!: overhaul keymap utility

* feat: can toggle showing wrapped tasks

* doc: improve type annotations for config

* feat: save template name and params on tasks for serialization

* fix: disable autocmds when updating quickfix

* feat: expose API for creating a task output view

* refactor: tidy and trim config options

* doc: more docstrings for render.lua utilities

* doc: remove strategies from vimdocs

* refactor!: rename task "bundleable" property to "ephemeral"

* doc: fix typechecking

* refactor: mark wrap_builtins as experimental

* refactor: extract highlight creation into function

* feat: re-introduce config to customize default jobstart strategy

* refactor: delete the run_cmd API

* refactor!: make list_tasks sort order more stable

* fix: reduce cursor jumping in task list

* fix: register_alias doesn't override existing values by default

* cleanup: remove unused parameter in make template

* refactor!: rename actions -> keymap

* feat: OverseerShell can create tasks without starting them

* doc: add recipe for abbreviating OverseerShell

* feat: add another helper sort function

* refactor!: remove OverseerQuickAction command

* doc: add some more docs to function signatures

* doc: add more docs for output parsers

* fix: slightly smarter open_output behavior

* ci: drop neovim v0.10 from tests

* lint: fix luacheck errors

* doc: more resources for customizing task list rendering

* doc: update more of the docs for the upcoming changes

* refactor!: return truthy value from event to unsubscribe

* doc: add a section on subscribing to task events

* doc: add help docs for keymaps

* refactor!: Task:dispose() returns true if task was already disposed

* doc: add Task methods to API documentation

* doc: add Task fields to API documentation

Author: stevearc

.github/workflows/tests.yml

@@ -11,7 +11,7 @@ on:
 jobs:
   luacheck:
     name: Luacheck
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
 
@@ -27,37 +27,34 @@ jobs:
 
   stylua:
     name: StyLua
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - name: Stylua
         uses: JohnnyMorganz/stylua-action@v4
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          version: v2.0.2
+          version: v2.3.0
           args: --check lua tests
 
   typecheck:
     name: typecheck
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
       - uses: stevearc/nvim-typecheck-action@v2
         with:
           path: lua
-          libraries: https://github.com/nvim-neotest/neotest https://github.com/mfussenegger/nvim-dap https://github.com/akinsho/toggleterm.nvim
+          libraries: https://github.com/nvim-neotest/neotest https://github.com/mfussenegger/nvim-dap
 
   run_tests:
     strategy:
       matrix:
         nvim_tag:
-          - v0.8.3
-          - v0.9.4
-          - v0.10.0
-          - v0.10.4
+          - v0.11.0
 
     name: Run tests
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     env:
       NVIM_TAG: ${{ matrix.nvim_tag }}
     steps:
@@ -73,7 +70,7 @@ jobs:
 
   update_docs:
     name: Update docs
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
 
@@ -110,7 +107,7 @@ jobs:
       - typecheck
       - run_tests
       - update_docs
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
       - uses: googleapis/release-please-action@v4
         id: release

Makefile

@@ -1,19 +1,37 @@
-.PHONY: all doc test lint fastlint clean
-
+## help: print this help message
+.PHONY: help
+help:
+	@echo 'Usage:'
+	@sed -n 's/^##//p' ${MAKEFILE_LIST} | column -t -s ':' |  sed -e 's/^/ /'
+
+## all: generate docs, lint, and run tests
+.PHONY: all
 all: doc lint test
 
-doc: scripts/nvim_doc_tools
-	python scripts/main.py generate
-	python scripts/main.py lint
+venv:
+	python3 -m venv venv
+	venv/bin/pip install -r scripts/requirements.txt
+
+## doc: generate documentation
+.PHONY: doc
+doc: scripts/nvim_doc_tools venv
+	venv/bin/python scripts/main.py generate
+	venv/bin/python scripts/main.py lint
 
+## test: run tests
+.PHONY: test
 test:
 	./run_tests.sh
 
+## lint: run linters and LuaLS typechecking
+.PHONY: lint
 lint: scripts/nvim-typecheck-action fastlint
-	./scripts/nvim-typecheck-action/typecheck.sh --lib https://github.com/nvim-neotest/neotest --lib https://github.com/mfussenegger/nvim-dap --lib https://github.com/akinsho/toggleterm.nvim --workdir scripts/nvim-typecheck-action lua
+	./scripts/nvim-typecheck-action/typecheck.sh --lib https://github.com/nvim-neotest/neotest --lib https://github.com/mfussenegger/nvim-dap --workdir scripts/nvim-typecheck-action lua
 
-fastlint: scripts/nvim_doc_tools
-	python scripts/main.py lint
+## fastlint: run only fast linters
+.PHONY: fastlint
+fastlint: scripts/nvim_doc_tools venv
+	venv/bin/python scripts/main.py lint
 	luacheck lua tests --formatter plain
 	stylua --check lua tests
 
@@ -23,5 +41,7 @@ scripts/nvim_doc_tools:
 scripts/nvim-typecheck-action:
 	git clone https://github.com/stevearc/nvim-typecheck-action scripts/nvim-typecheck-action
 
+## clean: reset the repository to a clean state
+.PHONY: clean
 clean:
 	rm -rf scripts/nvim_doc_tools scripts/nvim-typecheck-action venv .testenv

README.md

@@ -15,7 +15,9 @@ A task runner and job management plugin for Neovim
   - [Custom tasks](doc/guides.md#custom-tasks)
   - [Actions](doc/guides.md#actions)
   - [Custom components](doc/guides.md#custom-components)
+  - [Task events](doc/guides.md#task-events)
   - [Customizing built-in tasks](doc/guides.md#customizing-built-in-tasks)
+  - [Customizing the task appearance in the task list](doc/guides.md#customizing-the-task-appearance-in-the-task-list)
   - [Parsing output](doc/guides.md#parsing-output)
   - [Running tasks sequentially](doc/guides.md#running-tasks-sequentially)
   - [VS Code tasks](doc/guides.md#vs-code-tasks)
@@ -30,22 +32,22 @@ A task runner and job management plugin for Neovim
   - [Heirline](doc/third_party.md#heirline)
   - [Neotest](doc/third_party.md#neotest)
   - [DAP](doc/third_party.md#dap)
-  - [ToggleTerm](doc/third_party.md#toggleterm)
   - [Session managers](doc/third_party.md#session-managers)
 - [Recipes](#recipes)
+  - [Run a quick command like with `:!` or `:term`](doc/recipes.md#run-a-quick-command-like-with--or-term)
   - [Restart last task](doc/recipes.md#restart-last-task)
   - [Run shell scripts in the current directory](doc/recipes.md#run-shell-scripts-in-the-current-directory)
   - [Directory-local tasks with exrc](doc/recipes.md#directory-local-tasks-with-exrc)
-  - [:Make similar to vim-dispatch](doc/recipes.md#make-similar-to-vim-dispatch)
+  - [Asynchronous :Make similar to vim-dispatch](doc/recipes.md#asynchronous-make-similar-to-vim-dispatch)
   - [Asynchronous :Grep command](doc/recipes.md#asynchronous-grep-command)
+  - [Create a window that displays the most recent task output](doc/recipes.md#create-a-window-that-displays-the-most-recent-task-output)
 - [Reference](#reference)
   - [Setup options](doc/reference.md#setup-options)
   - [Commands](doc/reference.md#commands)
   - [Highlight groups](doc/reference.md#highlight-groups)
   - [Lua API](doc/reference.md#lua-api)
   - [Components](doc/reference.md#components)
   - [Strategies](doc/reference.md#strategies)
-  - [Parsers](doc/reference.md#parsers)
   - [Parameters](doc/reference.md#parameters)
 - [Screenshots](#screenshots)
 
@@ -54,7 +56,7 @@ A task runner and job management plugin for Neovim
 ## Features
 
 - Built-in support for many task frameworks (make, npm, cargo, `.vscode/tasks.json`, etc)
-- Simple integration with vim.diagnostics and quickfix
+- Simple integration with `vim.diagnostic` and quickfix
 - UI for viewing and managing tasks
 - Quick controls for common actions (restart task, rerun on save, or user-defined functions)
 - Extreme customizability. Very easy to attach custom logic to tasks
@@ -63,7 +65,7 @@ A task runner and job management plugin for Neovim
 
 ## Requirements
 
-- Neovim 0.8+ (for older versions, use the [nvim-0.7 branch](https://github.com/stevearc/overseer.nvim/tree/nvim-0.7))
+- Neovim 0.11+ (for older versions, use a [nvim-0.x branch](https://github.com/stevearc/overseer.nvim/branches))
 
 ## Installation
 
@@ -75,6 +77,8 @@ overseer supports all the usual plugin managers
 ```lua
 {
   'stevearc/overseer.nvim',
+  ---@module 'overseer'
+  ---@type overseer.SetupOpts
   opts = {},
 }
 ```
@@ -85,11 +89,13 @@ overseer supports all the usual plugin managers
   <summary>Packer</summary>
 
 ```lua
-require('packer').startup(function()
-    use {
-      'stevearc/overseer.nvim',
-      config = function() require('overseer').setup() end
-    }
+require("packer").startup(function()
+  use({
+    "stevearc/overseer.nvim",
+    config = function()
+      require("overseer").setup()
+    end,
+  })
 end)
 ```
 
@@ -99,9 +105,9 @@ end)
   <summary>Paq</summary>
 
 ```lua
-require "paq" {
-    {'stevearc/overseer.nvim'};
-}
+require("paq")({
+  { "stevearc/overseer.nvim" },
+})
 ```
 
 </details>
@@ -148,14 +154,14 @@ git clone --depth=1 https://github.com/stevearc/overseer.nvim.git \
 Add the following to your init.lua
 
 ```lua
-require('overseer').setup()
+require("overseer").setup()
 ```
 
 To get started, all you need to know is `:OverseerRun` to select and start a task, and `:OverseerToggle` to open the task list.
 
 https://user-images.githubusercontent.com/506791/189036898-05edcd62-42e7-4bbb-ace2-746b7c8c567b.mp4
 
-If you don't see any tasks from `:OverseerRun`, it might mean that your task runner is not yet supported. There is currently support for VS Code tasks, make, npm, cargo, and some others. If yours is not supported, ([request support here](https://github.com/stevearc/overseer.nvim/issues/new/choose)).
+If you don't see any tasks from `:OverseerRun`, it might mean that your task runner is not yet supported. There is currently support for VS Code tasks, make, npm, cargo, and some others.
 
 If you want to define custom tasks for your project, I'd recommend starting with [the tutorials](doc/tutorials.md).
 
@@ -173,7 +179,9 @@ If you want to define custom tasks for your project, I'd recommend starting with
 - [Custom components](doc/guides.md#custom-components)
   - [Component aliases](doc/guides.md#component-aliases)
   - [Task result](doc/guides.md#task-result)
+- [Task events](doc/guides.md#task-events)
 - [Customizing built-in tasks](doc/guides.md#customizing-built-in-tasks)
+- [Customizing the task appearance in the task list](doc/guides.md#customizing-the-task-appearance-in-the-task-list)
 - [Parsing output](doc/guides.md#parsing-output)
 - [Running tasks sequentially](doc/guides.md#running-tasks-sequentially)
 - [VS Code tasks](doc/guides.md#vs-code-tasks)
@@ -183,6 +191,7 @@ If you want to define custom tasks for your project, I'd recommend starting with
 - [Architecture](doc/explanation.md#architecture)
   - [Tasks](doc/explanation.md#tasks)
   - [Components](doc/explanation.md#components)
+  - [Serializability](doc/explanation.md#serializability)
   - [Templates](doc/explanation.md#templates)
 - [Task list](doc/explanation.md#task-list)
 - [Task editor](doc/explanation.md#task-editor)
@@ -195,18 +204,19 @@ If you want to define custom tasks for your project, I'd recommend starting with
 - [Heirline](doc/third_party.md#heirline)
 - [Neotest](doc/third_party.md#neotest)
 - [DAP](doc/third_party.md#dap)
-- [ToggleTerm](doc/third_party.md#toggleterm)
 - [Session managers](doc/third_party.md#session-managers)
   - [resession.nvim](doc/third_party.md#resessionnvim)
   - [Other session managers](doc/third_party.md#other-session-managers)
 
 ## Recipes
 
+- [Run a quick command like with `:!` or `:term`](doc/recipes.md#run-a-quick-command-like-with--or-term)
 - [Restart last task](doc/recipes.md#restart-last-task)
 - [Run shell scripts in the current directory](doc/recipes.md#run-shell-scripts-in-the-current-directory)
 - [Directory-local tasks with exrc](doc/recipes.md#directory-local-tasks-with-exrc)
-- [:Make similar to vim-dispatch](doc/recipes.md#make-similar-to-vim-dispatch)
+- [Asynchronous :Make similar to vim-dispatch](doc/recipes.md#asynchronous-make-similar-to-vim-dispatch)
 - [Asynchronous :Grep command](doc/recipes.md#asynchronous-grep-command)
+- [Create a window that displays the most recent task output](doc/recipes.md#create-a-window-that-displays-the-most-recent-task-output)
 
 ## Reference
 
@@ -215,30 +225,49 @@ If you want to define custom tasks for your project, I'd recommend starting with
 - [Highlight groups](doc/reference.md#highlight-groups)
 - [Lua API](doc/reference.md#lua-api)
   - [setup(opts)](doc/reference.md#setupopts)
-  - [on_setup(callback)](doc/reference.md#on_setupcallback)
   - [new_task(opts)](doc/reference.md#new_taskopts)
   - [toggle(opts)](doc/reference.md#toggleopts)
   - [open(opts)](doc/reference.md#openopts)
   - [close()](doc/reference.md#close)
-  - [list_task_bundles()](doc/reference.md#list_task_bundles)
-  - [load_task_bundle(name, opts)](doc/reference.md#load_task_bundlename-opts)
-  - [save_task_bundle(name, tasks, opts)](doc/reference.md#save_task_bundlename-tasks-opts)
-  - [delete_task_bundle(name)](doc/reference.md#delete_task_bundlename)
   - [list_tasks(opts)](doc/reference.md#list_tasksopts)
-  - [run_template(opts, callback)](doc/reference.md#run_templateopts-callback)
+  - [run_task(opts, callback)](doc/reference.md#run_taskopts-callback)
   - [preload_task_cache(opts, cb)](doc/reference.md#preload_task_cacheopts-cb)
   - [clear_task_cache(opts)](doc/reference.md#clear_task_cacheopts)
   - [run_action(task, name)](doc/reference.md#run_actiontask-name)
-  - [wrap_template(base, override, default_params)](doc/reference.md#wrap_templatebase-override-default_params)
   - [add_template_hook(opts, hook)](doc/reference.md#add_template_hookopts-hook)
   - [remove_template_hook(opts, hook)](doc/reference.md#remove_template_hookopts-hook)
   - [register_template(defn)](doc/reference.md#register_templatedefn)
-  - [load_template(name)](doc/reference.md#load_templatename)
-  - [debug_parser()](doc/reference.md#debug_parser)
-  - [register_alias(name, components)](doc/reference.md#register_aliasname-components)
+  - [register_alias(name, components, override)](doc/reference.md#register_aliasname-components-override)
+  - [create_task_output_view(winid, opts)](doc/reference.md#create_task_output_viewwinid-opts)
+  - [overseer.Task](doc/reference.md#overseertask)
+    - [Task:serialize()](doc/reference.md#taskserialize)
+    - [Task:clone()](doc/reference.md#taskclone)
+    - [Task:add_component(comp)](doc/reference.md#taskadd_componentcomp)
+    - [Task:add_components(components)](doc/reference.md#taskadd_componentscomponents)
+    - [Task:set_component(comp)](doc/reference.md#taskset_componentcomp)
+    - [Task:set_components(components)](doc/reference.md#taskset_componentscomponents)
+    - [Task:get_component(name)](doc/reference.md#taskget_componentname)
+    - [Task:remove_component(name)](doc/reference.md#taskremove_componentname)
+    - [Task:remove_components(names)](doc/reference.md#taskremove_componentsnames)
+    - [Task:has_component(name)](doc/reference.md#taskhas_componentname)
+    - [Task:subscribe(event, callback)](doc/reference.md#tasksubscribeevent-callback)
+    - [Task:unsubscribe(event, callback)](doc/reference.md#taskunsubscribeevent-callback)
+    - [Task:is_pending()](doc/reference.md#taskis_pending)
+    - [Task:is_running()](doc/reference.md#taskis_running)
+    - [Task:is_complete()](doc/reference.md#taskis_complete)
+    - [Task:is_disposed()](doc/reference.md#taskis_disposed)
+    - [Task:get_bufnr()](doc/reference.md#taskget_bufnr)
+    - [Task:open_output(direction)](doc/reference.md#taskopen_outputdirection)
+    - [Task:broadcast(name)](doc/reference.md#taskbroadcastname)
+    - [Task:dispatch(name)](doc/reference.md#taskdispatchname)
+    - [Task:inc_reference()](doc/reference.md#taskinc_reference)
+    - [Task:dec_reference()](doc/reference.md#taskdec_reference)
+    - [Task:dispose(force)](doc/reference.md#taskdisposeforce)
+    - [Task:restart(force_stop)](doc/reference.md#taskrestartforce_stop)
+    - [Task:start()](doc/reference.md#taskstart)
+    - [Task:stop()](doc/reference.md#taskstop)
 - [Components](doc/reference.md#components)
 - [Strategies](doc/reference.md#strategies)
-- [Parsers](doc/reference.md#parsers)
 - [Parameters](doc/reference.md#parameters)
 
 ## Screenshots