fix: correctness pass over error handling, argument parsing and repo commands

.luacheckrc

@@ -15,4 +15,7 @@ exclude_files = {
 
 files['tests/'] = {
   std = '+busted',
+  -- Specs stub `vim` fields such as `vim.notify` to capture output,
+  -- so the table is writable here even though plugin code may only read it.
+  globals = { 'vim' },
 }

README.md

@@ -12,7 +12,7 @@ Every agitate command starts with `:Agitate` and is followed by the
 context and the action. Example:
 
 ```vim
-:AgitateRepoCreateGitHub
+:AgitateRepoCreate
 ```
 
 ### Available contexts
@@ -25,11 +25,11 @@ You can easily verify what the commands are and what they do by looking at the
 
 #### Repo
 
-- `:AgitateRepoCreateGitHub` - Create a new remote repository on GitHub.  
+- `:AgitateRepoCreate` - Create a new remote repository on GitHub.  
   Uses the repository name provided as an optional argument **_or_** the current
   directory as the repository name if no argument is provided.
 
-- `:AgitateRepoInitGitHub` - Initializes the current directory as a GitHub
+- `:AgitateRepoInit` - Initializes the current directory as a GitHub
   repository.  
   Uses the repository name provided as an optional argument **_or_** the current
   directory as the repository name if no argument is provided.
@@ -50,16 +50,16 @@ to bind them to a keybinding to be able to use `Agitate` with less friction.
 vimscript:
 
 ```vim
-nnoremap <leader>gil :AgitateRepoInitGitHub
-nnoremap <leader>gir :AgitateRepoCreateGitHub
+nnoremap <leader>gil :AgitateRepoInit
+nnoremap <leader>gir :AgitateRepoCreate
 nnoremap <leader>gbp :AgitateBranchCreateCheckoutAndPush
 ```
 
 lua:
 
 ```lua
-vim.keymap.set('n', '<leader>gil', ':AgitateRepoInitGitHub ')
-vim.keymap.set('n', '<leader>gir', ':AgitateRepoCreateGitHub ')
+vim.keymap.set('n', '<leader>gil', ':AgitateRepoInit ')
+vim.keymap.set('n', '<leader>gir', ':AgitateRepoCreate ')
 vim.keymap.set('n', '<leader>gbp', ':AgitateBranchCreateCheckoutAndPush ')
 ```
 
@@ -146,7 +146,10 @@ Features planned for implementation
   - todo!()
 
 - [ ] Project functions:
-  - todo!()
+  - Blocked. The classic Projects REST API has been sunset and Projects V2 is
+    reachable only through GraphQL, so this needs a GraphQL client alongside
+    the REST one and a token carrying the `project` scope. Worth revisiting
+    once the REST backed features have landed.
 
 ## Contributing
 

lua/agitate/api/branch.lua

@@ -1,15 +1,17 @@
 local M = {}
 
-local ok, error = pcall(require, 'agitate.error')
+local ok, agitate_error = pcall(require, 'agitate.error')
 if not ok then
-  return vim.api.nvim_err_writeln(require('agitate.const.error').import)
+  local message = require('agitate.const.error').import
+  vim.notify(message, vim.log.levels.ERROR)
+  error(message, 0)
 end
 
 function M.setup()
   vim.api.nvim_create_user_command('AgitateBranchCreateCheckoutAndPush', function(opts)
     local branch_ok, branch_or_err = pcall(require, 'agitate.core.branch')
     if not branch_ok then
-      return error.throw(branch_or_err)
+      return agitate_error.throw(branch_or_err)
     end
 
     branch_or_err.CreateCheckoutAndPush(opts.fargs[1])

lua/agitate/api/init.lua

@@ -1,23 +1,25 @@
 local M = {}
 
-local ok, error = pcall(require, 'agitate.error')
+local ok, agitate_error = pcall(require, 'agitate.error')
 if not ok then
-  return vim.api.nvim_err_writeln(require('agitate.const.error').import)
+  local message = require('agitate.const.error').import
+  vim.notify(message, vim.log.levels.ERROR)
+  error(message, 0)
 end
 
 function M.setup()
   local branch_ok, branch_or_err = pcall(require, 'agitate.api.branch')
   if branch_ok then
     branch_or_err.setup()
   else
-    error.throw(branch_or_err)
+    agitate_error.throw(branch_or_err)
   end
 
   local repo_ok, repo_or_err = pcall(require, 'agitate.api.repo')
   if repo_ok then
     repo_or_err.setup()
   else
-    error.throw(repo_or_err)
+    agitate_error.throw(repo_or_err)
   end
 end
 

lua/agitate/api/repo.lua

@@ -1,30 +1,32 @@
 local M = {}
 
-local ok, error = pcall(require, 'agitate.error')
+local ok, agitate_error = pcall(require, 'agitate.error')
 if not ok then
-  return vim.api.nvim_err_writeln(require('agitate.const.error').import)
+  local message = require('agitate.const.error').import
+  vim.notify(message, vim.log.levels.ERROR)
+  error(message, 0)
 end
 
 function M.setup()
-  vim.api.nvim_create_user_command('AgitateRepoCreateGitHub', function(opts)
+  vim.api.nvim_create_user_command('AgitateRepoCreate', function(opts)
     local repo_ok, repo_or_err = pcall(require, 'agitate.core.repo')
     if not repo_ok then
-      return error.throw(repo_or_err)
+      return agitate_error.throw(repo_or_err)
     end
 
-    repo_or_err.CreateGitHubCurl(opts.fargs)
+    repo_or_err.Create(opts.fargs)
   end, {
     nargs = '*',
     desc = "Creates a new repository at 'github.com/<github_username>/<argument or current_directory>/'",
   })
 
-  vim.api.nvim_create_user_command('AgitateRepoInitGitHub', function(opts)
+  vim.api.nvim_create_user_command('AgitateRepoInit', function(opts)
     local repo_ok, repo_or_err = pcall(require, 'agitate.core.repo')
     if not repo_ok then
-      return error.throw(repo_or_err)
+      return agitate_error.throw(repo_or_err)
     end
 
-    repo_or_err.InitGitHub(opts.fargs)
+    repo_or_err.Init(opts.fargs)
   end, {
     nargs = '*',
     desc = "Initialize the current directory as a repository at 'github.com/<github_username>/<argument or current_directory>/'",

lua/agitate/config.lua

@@ -1,13 +1,16 @@
 local M = {}
 
-local ok, error = pcall(require, 'agitate.error')
+local ok, agitate_error = pcall(require, 'agitate.error')
 if not ok then
-  return vim.api.nvim_err_writeln(require('agitate.const.error').import)
+  local message = require('agitate.const.error').import
+  vim.notify(message, vim.log.levels.ERROR)
+  error(message, 0)
 end
 
 local types_ok, types_or_err = pcall(require, 'agitate.types.config')
 if not types_ok then
-  return error.throw(types_or_err)
+  agitate_error.throw(types_or_err)
+  error(types_or_err, 0)
 end
 
 ---@type Config
@@ -33,7 +36,11 @@ function M.setup(options)
   if api_ok then
     api_or_err.setup()
   else
-    error.throw(api_or_err)
+    -- Raised rather than reported and shrugged off. Without the api module no
+    -- commands exist, so continuing leaves the plugin loaded and inert, which
+    -- is harder to diagnose than a failed setup.
+    agitate_error.throw(api_or_err)
+    error(api_or_err, 0)
   end
 end
 

lua/agitate/core/branch.lua

@@ -5,7 +5,7 @@ function M.CreateCheckoutAndPush(branch_name)
     vim.cmd('G checkout -b ' .. branch_name)
     vim.cmd('G push -u origin ' .. branch_name)
   else
-    print('Please provide an argument for the name of the branch')
+    vim.notify('core.branch.CreateCheckoutAndPush -- Error: no branch name provided', vim.log.levels.ERROR)
   end
 end