test(commands): add boundary contracts and guards

Codify command-layer invariants so the refactor is reviewable and regression-safe. The tests lock parser/dispatcher behavior, handler boundaries, keymap routing, and registry contracts while tightening shared types used by those checks.

Author: oujinsai

lua/opencode/commands/handlers/agent.lua

@@ -1,5 +1,6 @@
 local core = require('opencode.core')
 local config_file = require('opencode.config_file')
+---@type OpencodeState
 local state = require('opencode.state')
 local util = require('opencode.util')
 local Promise = require('opencode.promise')

lua/opencode/commands/handlers/diff.lua

@@ -1,6 +1,7 @@
 local core = require('opencode.core')
 local git_review = require('opencode.git_review')
 local session_store = require('opencode.session')
+---@type OpencodeState
 local state = require('opencode.state')
 
 local M = {

lua/opencode/commands/handlers/permission.lua

@@ -1,3 +1,4 @@
+---@type OpencodeState
 local state = require('opencode.state')
 
 local M = {

lua/opencode/commands/handlers/session.lua

@@ -3,6 +3,13 @@ local M = {
   handlers = {},
 }
 
+local core = require('opencode.core')
+---@type OpencodeState
+local state = require('opencode.state')
+local session_store = require('opencode.session')
+local Promise = require('opencode.promise')
+local window_actions = require('opencode.commands.handlers.window').actions
+
 ---@param message string
 local function invalid_arguments(message)
   error({
@@ -11,57 +18,37 @@ local function invalid_arguments(message)
   }, 0)
 end
 
-local function core()
-  return require('opencode.core')
-end
-
-local function state()
-  return require('opencode.state')
-end
-
-local function session_store()
-  return require('opencode.session')
-end
-
-local function Promise()
-  return require('opencode.promise')
-end
-
-local function window_actions()
-  return require('opencode.commands.handlers.window').actions
-end
-
 function M.actions.open_input_new_session()
-  return core().open({ new_session = true, focus = 'input', start_insert = true })
+  return core.open({ new_session = true, focus = 'input', start_insert = true })
 end
 
 ---@param title string
 function M.actions.open_input_new_session_with_title(title)
-  return Promise().async(function(session_title)
-    local new_session = core().create_new_session(session_title):await()
+  return Promise.async(function(session_title)
+    local new_session = core.create_new_session(session_title):await()
     if not new_session then
       vim.notify('Failed to create new session', vim.log.levels.ERROR)
       return
     end
 
-    state().session.set_active(new_session)
-    return window_actions().open_input()
+    state.session.set_active(new_session)
+    return window_actions.open_input()
   end)(title)
 end
 
 ---@param parent_id? string
 function M.actions.select_session(parent_id)
-  core().select_session(parent_id)
+  core.select_session(parent_id)
 end
 
 function M.actions.select_child_session()
-  local active = state().active_session
-  core().select_session(active and active.id or nil)
+  local active = state.active_session
+  core.select_session(active and active.id or nil)
 end
 
 ---@param current_session? Session
 function M.actions.compact_session(current_session)
-  local state_obj = state()
+  local state_obj = state
   current_session = current_session or state_obj.active_session
   if not current_session then
     vim.notify('No active session to compact', vim.log.levels.WARN)
@@ -98,7 +85,7 @@ function M.actions.compact_session(current_session)
 end
 
 function M.actions.share()
-  local state_obj = state()
+  local state_obj = state
   if not state_obj.active_session then
     vim.notify('No active session to share', vim.log.levels.WARN)
     return
@@ -124,7 +111,7 @@ function M.actions.share()
 end
 
 function M.actions.unshare()
-  local state_obj = state()
+  local state_obj = state
   if not state_obj.active_session then
     vim.notify('No active session to unshare', vim.log.levels.WARN)
     return
@@ -145,10 +132,10 @@ function M.actions.unshare()
 end
 
 function M.actions.initialize()
-  return Promise().async(function()
+  return Promise.async(function()
     local id = require('opencode.id')
-    local state_obj = state()
-    local core_obj = core()
+    local state_obj = state
+    local core_obj = core
 
     local new_session = core_obj.create_new_session('AGENTS.md Initialization'):await()
     if not new_session then
@@ -168,7 +155,7 @@ function M.actions.initialize()
     end
 
     state_obj.session.set_active(new_session)
-    window_actions().open_input()
+    window_actions.open_input()
     state_obj.api_client:init_session(state_obj.active_session.id, {
       providerID = providerId,
       modelID = modelId,
@@ -180,9 +167,9 @@ end
 ---@param current_session? Session
 ---@param new_title? string
 function M.actions.rename_session(current_session, new_title)
-  return Promise().async(function(session_obj, requested_title)
-    local promise = Promise().new()
-    local state_obj = state()
+  return Promise.async(function(session_obj, requested_title)
+    local promise = Promise.new()
+    local state_obj = state
     session_obj = session_obj or (state_obj.active_session and vim.deepcopy(state_obj.active_session) or nil) --[[@as Session]]
     if not session_obj then
       vim.notify('No active session to rename', vim.log.levels.WARN)
@@ -198,10 +185,10 @@ function M.actions.rename_session(current_session, new_title)
             vim.notify('Failed to rename session: ' .. vim.inspect(err), vim.log.levels.ERROR)
           end)
         end)
-        :and_then(Promise().async(function()
+        :and_then(Promise.async(function()
           session_obj.title = title
           if state_obj.active_session and state_obj.active_session.id == session_obj.id then
-            local persisted_session = session_store().get_by_id(session_obj.id):await()
+              local persisted_session = session_store.get_by_id(session_obj.id):await()
             if persisted_session then
               persisted_session.title = title
               state_obj.session.set_active(vim.deepcopy(persisted_session))

lua/opencode/commands/handlers/window.lua

@@ -1,4 +1,5 @@
 local core = require('opencode.core')
+---@type OpencodeState
 local state = require('opencode.state')
 local ui = require('opencode.ui.ui')
 local config = require('opencode.config')

lua/opencode/commands/handlers/workflow.lua

@@ -1,6 +1,7 @@
 local core = require('opencode.core')
 local util = require('opencode.util')
 local config_file = require('opencode.config_file')
+---@type OpencodeState
 local state = require('opencode.state')
 local quick_chat = require('opencode.quick_chat')
 local history = require('opencode.history')

lua/opencode/state/init.lua

@@ -6,16 +6,17 @@ local model = require('opencode.state.model')
 local renderer = require('opencode.state.renderer')
 local context = require('opencode.state.context')
 
----@class OpencodeStateModule
+---@class OpencodeState : OpencodeStateData
 ---@field store OpencodeStateStore
 ---@field session OpencodeSessionStateMutations
 ---@field jobs OpencodeJobStateMutations
 ---@field ui OpencodeUiStateMutations
 ---@field model OpencodeModelStateMutations
 ---@field renderer OpencodeRendererStateMutations
 ---@field context OpencodeContextStateMutations
-
----@alias OpencodeState OpencodeStateModule & OpencodeStateData
+---@field active_session Session|nil
+---@field current_model string|nil
+---@field api_client OpencodeApiClient|nil
 
 ---@type OpencodeState
 local M = {