v2.0 breaking changes refactor

.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