refactor(codex): init is mainly a facade, no behavior change (#10)

Reviewed-on: https://codeberg.org/yaadata/codex.nvim/pulls/10
Co-authored-by: Yadi Abdalhalim <abdalhalim.yaadata@gmail.com>
Co-committed-by: Yadi Abdalhalim <abdalhalim.yaadata@gmail.com>

Author: yaadata

docs/architecture.md

@@ -5,15 +5,16 @@
 codex.nvim is a Neovim plugin that orchestrates an embedded terminal session for
 the Codex CLI. The architecture centres on a **pluggable provider** abstraction:
 all terminal management (opening, closing, sending text, focus, toggling) is
-delegated to a provider that satisfies a 9-method interface contract, while the
-core module (`init.lua`) owns session lifecycle, dependency wiring, and the
-public Lua API.
+delegated to a provider that satisfies a 9-method interface contract. The core
+module (`init.lua`) acts as a thin **facade** -- it owns dependency wiring and
+the public Lua API, while delegating session lifecycle, send dispatch, and
+mention orchestration to dedicated modules.
 
 ```
 plugin/codex.lua          (entry point, version guard, load guard)
         │
         ▼
-lua/codex/init.lua        (public API, session lifecycle, DI container)
+lua/codex/init.lua        (public API facade, DI container, setup wiring)
         │
         ├──► config.lua           (defaults, validation, deep merge)
         ├──► logger.lua           (level-gated vim.notify wrapper)
@@ -24,12 +25,16 @@ lua/codex/init.lua        (public API, session lifecycle, DI container)
         │        └── snacks.lua
         ├──► context/
         │        ├── formatter.lua  (selection + mention payload formatting)
+        │        ├── mention.lua    (mention orchestration, prompt capture/restore)
         │        ├── path.lua       (CWD-relative path normalization)
         │        └── selection.lua  (visual selection extraction)
         ├──► runtime/
-        │        └── send_queue.lua (FIFO queue + retry timer for startup readiness)
+        │        ├── send_dispatch.lua  (send pipeline, queue/retry orchestration)
+        │        ├── send_queue.lua     (FIFO queue + retry timer for startup readiness)
+        │        └── terminal_io.lua    (terminal I/O utilities + constants)
         └──► state/
-                 └── session_store.lua  (session registry, alive/dead tracking)
+                 ├── session_lifecycle.lua  (session open/close/toggle/focus operations)
+                 └── session_store.lua      (session registry, alive/dead tracking)
 ```
 
 ## Directory Layout
@@ -40,9 +45,9 @@ codex.nvim/
 │   └── codex.lua                    # Entry point. Guards Neovim >= 0.11.0 and
 │                                    # prevents double-loading via vim.g.loaded_codex.
 ├── lua/codex/
-│   ├── init.lua                     # Public API surface (setup, open, close, toggle,
+│   ├── init.lua                     # Public API facade (setup, open, close, toggle,
 │   │                                # send, send_selection, mention_file, mention_directory, resume, etc.).
-│   │                                # Owns the DI container and session lifecycle.
+│   │                                # Owns the DI container, setup wiring, and thin delegates.
 │   ├── config.lua                   # Default config table, vim.validate-based
 │   │                                # validation, and deep-merge with user options.
 │   ├── types.lua                    # EmmyLua annotations only (no runtime code).
@@ -66,15 +71,28 @@ codex.nvim/
 │   │   ├── formatter.lua            # Formats selection payloads (fenced code blocks with
 │   │   │                            # adaptive backtick fencing) and /mention payloads
 │   │   │                            # (auto-quoting paths with special characters).
+│   │   ├── mention.lua              # Mention orchestration: captures terminal prompt input,
+│   │   │                            # dispatches /mention payloads, auto-submits, and restores
+│   │   │                            # previously typed text. Uses create(opts) constructor.
 │   │   ├── path.lua                 # Normalizes file paths to CWD-relative form via
 │   │   │                            # fnamemodify(":."). Falls back to the original path
 │   │   │                            # on error.
 │   │   └── selection.lua            # Extracts visual selection from the current buffer.
 │   │                                # Resolves range via command args or visual marks.
 │   ├── runtime/
-│   │   └── send_queue.lua           # Startup-readiness send queue. Owns retry scheduling
-│   │                                # and FIFO flushing for deferred payload dispatch.
+│   │   ├── send_dispatch.lua        # Send pipeline with startup/retry orchestration.
+│   │   │                            # Builds PendingSend items, submits to send_queue,
+│   │   │                            # handles session readiness checks and timeout logic.
+│   │   │                            # Uses create(opts) constructor.
+│   │   ├── send_queue.lua           # Startup-readiness send queue. Owns retry scheduling
+│   │   │                            # and FIFO flushing for deferred payload dispatch.
+│   │   └── terminal_io.lua          # Pure/near-pure terminal I/O utilities: bracketed paste
+│   │                                # encoding, termcode expansion, prompt line parsing,
+│   │                                # ANSI stripping, and shared constants.
 │   └── state/
+│       ├── session_lifecycle.lua    # Session lifecycle operations: open, close, toggle,
+│       │                            # focus, alive/ready checks, post-send refocus.
+│       │                            # All functions take (deps, config) explicitly.
 │       └── session_store.lua        # In-memory session registry. Tracks sessions by ID
 │                                    # with alive/dead lifecycle, active session pointer,
 │                                    # and monotonic counter for ID generation.
@@ -98,9 +116,11 @@ codex.nvim/
 
 ## Key Design Patterns
 
-### Module Pattern
+### Module Patterns
 
-Every Lua module follows the standard Neovim module pattern:
+#### Stateless modules
+
+Most modules follow the standard Neovim module pattern:
 
 ```lua
 local M = {}
@@ -115,7 +135,36 @@ return M
 ```
 
 Functions on `M` are the public API; bare `local function` declarations are
-private. This convention is consistent across every file in `lua/codex/`.
+private. Examples: `terminal_io.lua`, `session_lifecycle.lua`, `config.lua`.
+
+#### Constructor modules
+
+Modules that need runtime accessors (closures over `get_deps`, `get_config`,
+etc.) use a `create(opts)` constructor that returns a table of bound functions:
+
+```lua
+local M = {}
+
+function M.create(opts)
+  local get_deps = opts.get_deps
+
+  local function private_helper() ... end
+
+  local function public_method()
+    local deps = get_deps()
+    ...
+  end
+
+  return { public_method = public_method }
+end
+
+return M
+```
+
+`init.lua` calls `create()` during `setup()` and stores the returned instance
+in `state`. This pattern avoids circular dependencies -- extracted modules never
+`require("codex")` back. Examples: `send_dispatch.lua`, `mention.lua`,
+`send_queue.lua`.
 
 ### Provider Abstraction
 
@@ -154,8 +203,13 @@ tracks:
 
 The store exposes `create`, `get`, `get_active`, `mark_dead`, `remove`, `list`,
 and `reset`. Only one session is "active" at a time. When a provider fires its
-`on_exit` callback, `init.lua` walks the session list to find the matching
-handle and calls `mark_dead`.
+`on_exit` callback, `session_lifecycle.mark_session_dead_by_handle()` walks the
+session list to find the matching handle and calls `mark_dead`.
+
+`state/session_lifecycle.lua` builds on the session store with higher-level
+operations: `open_session`, `close_session`, `toggle_session`, `focus_session`,
+and alive/ready checks. All functions take `(deps, config)` explicitly, making
+them stateless and testable without the full `init.lua` setup.
 
 ### Dependency Injection
 
@@ -182,6 +236,18 @@ override the corresponding defaults. The `_deps` key is then stripped before
 config validation. This enables full isolation in unit tests: every collaborator
 (including `vim` itself) can be replaced with a mock.
 
+After resolving deps and config, `setup()` wires the constructor modules:
+
+1. `send_dispatch.create()` -- receives `get_deps`, `get_config`,
+   `get_send_queue`, and an `open_session` closure.
+2. `send_queue.new()` -- receives the send dispatch's
+   `process_pending_send_item` as its process callback.
+3. `mention.create()` -- receives `get_deps`, `get_config`, and a
+   `dispatch_send` closure that delegates to the send dispatch instance.
+
+This wiring order allows `send_dispatch` to reference the send queue (via
+closure) even though the queue is created after the dispatch instance.
+
 ### Error Handling
 
 The codebase uses two error-reporting strategies:
@@ -202,15 +268,16 @@ failures downstream.
 ### Auto-Open
 
 APIs that need an active session (`send`, `send_command`, `focus`,
-`send_selection`, `mention_file`, `mention_directory`) automatically open one when needed. The
-lower-level `send` API opens without focus, while command-facing flows
-(`:CodexSend`, `:CodexAdd`) ensure the terminal is opened with focus before
-payload dispatch. If the provider handle is not yet ready, payloads are queued
-and retried on a timer (`terminal.startup.retry_interval_ms`) until ready or
-timeout (`terminal.startup.timeout_ms`). Queueing/scheduling is implemented in
-`runtime/send_queue.lua`, while `init.lua` owns session/open/reopen decisions.
-Providers apply a startup grace delay via `terminal.startup.grace_ms` before
-reporting readiness.
+`send_selection`, `mention_file`, `mention_directory`) automatically open one
+when needed. The lower-level `send` API opens without focus, while
+command-facing flows (`:CodexSend`, `:CodexMentionFile`) ensure the terminal is
+opened with focus before payload dispatch. If the provider handle is not yet
+ready, payloads are queued and retried on a timer
+(`terminal.startup.retry_interval_ms`) until ready or timeout
+(`terminal.startup.timeout_ms`). Queueing/scheduling is implemented in
+`runtime/send_queue.lua`, while `runtime/send_dispatch.lua` owns
+session/open/reopen decisions. Providers apply a startup grace delay via
+`terminal.startup.grace_ms` before reporting readiness.
 
 ## Component Interaction
 
@@ -243,6 +310,8 @@ Key types:
 | `codex.SelectionSpec`        | class | Visual selection data (defined in `formatter.lua`)            |
 | `codex.SelectionOpts`        | class | Options for selection extraction (defined in `selection.lua`) |
 | `codex.UserCommandOpts`      | class | Neovim user command callback argument shape                   |
+| `codex.PendingSend`          | class | Queued send item (defined in `send_dispatch.lua`)             |
+| `codex.DispatchSendOpts`     | class | Options for dispatch_send (defined in `send_dispatch.lua`)    |
 | `codex.ResumeOpts`           | class | Options for the resume API (defined in `init.lua`)            |
 | `codex.SendResult`           | alias | Boolean result alias (defined in `init.lua`)                  |
 

docs/command-interactions.md

@@ -3,8 +3,9 @@
 ## Overview
 
 This document is the canonical reference for how `:Codex*` commands map from
-`lua/codex/nvim/commands.lua` into the public API in `lua/codex/init.lua` and
-then into provider/session/runtime collaborators.
+`lua/codex/nvim/commands.lua` into the public API in `lua/codex/init.lua` (the
+facade) and then into `session_lifecycle`, `send_dispatch`, `mention`, and
+provider collaborators.
 
 ## Command Mapping
 
@@ -36,6 +37,9 @@ User calls require("codex").setup(opts)
 init.lua setup()
     |- build deps (default_deps + opts._deps)
     |- apply config defaults + validation
+    |- send_dispatch.create({ get_deps, get_config, get_send_queue, open_session })
+    |- send_queue.new({ process = send_dispatch.process_pending_send_item })
+    |- mention.create({ get_deps, get_config, dispatch_send })
     |- commands.register()
     |- keymaps.register(config)
     |    |- unregister stale Codex keymaps from previous setup
@@ -56,16 +60,15 @@ User runs :Codex (or :Codex!)
 commands.lua -> codex.toggle() (or codex.open(true) for :Codex!)
     |
     v
-init.lua
-    |- toggle():
-    |    |- ensure_setup()
+init.lua -> session_lifecycle
+    |- toggle_session(deps, config):
     |    |- session_store.get_active()
     |    |- providers.resolve(config.terminal.provider)
     |    |- [active + provider.is_alive(handle)]
     |    |    \- provider.toggle(handle, cmd, args, env, config)
     |    |        \- if new_handle returned, update session.handle
-    |    \- [no active session] open_session(args, focus=true)
-    \- open(true): open_session(args, focus=true)
+    |    \- [no active session] open_session(deps, config, args, focus=true)
+    \- open_session(deps, config, args, focus=true):
          |- provider.open(cmd, args, env, config, focus, on_exit_cb)
          \- session_store.create({ handle, cmd, cwd, provider_name })
 ```
@@ -79,11 +82,12 @@ User runs :CodexFocus
 commands.lua -> codex.focus()
     |
     v
-init.lua focus()
+init.lua focus() -> session_lifecycle
     |- ensure_setup()
-    |- session_store.get_active() + get_provider()
-    |- [active + alive] -> provider.focus(session.handle)
-    \- [no active/alive session] -> codex.open(true)
+    |- focus_session(deps, config)
+    |    |- session_store.get_active() + get_provider()
+    |    \- [active + alive] -> provider.focus(session.handle), return true
+    \- [not focused] -> codex.open(true)
 ```
 
 ### `:CodexClose`
@@ -95,7 +99,7 @@ User runs :CodexClose
 commands.lua -> codex.close()
     |
     v
-init.lua close()
+init.lua close() -> session_lifecycle.close_session(deps, config, send_queue)
     |- session_store.get_active()
     |- [no active session] -> send_queue.reset() and return
     \- [active session]
@@ -115,9 +119,9 @@ commands.lua -> codex.clear_input()
     v
 init.lua clear_input()
     |- ensure_setup()
-    |- session_store.get_active() + get_provider()
+    |- session_lifecycle.get_active_session_and_provider(deps, config)
     |- [no alive session] -> return false, "no active Codex session"
-    \- [alive session] -> provider.send(handle, encode_termcode("<C-c>"))
+    \- [alive session] -> provider.send(handle, terminal_io.encode_termcode(deps, "<C-c>"))
 ```
 
 ### `:CodexSend` (Range or Visual Selection)
@@ -140,9 +144,9 @@ init.lua send_selection()
     |    \- return SelectionSpec { path, start_line, end_line, filetype, lines }
     |- formatter.format_selection(spec)
     |    \- build fenced code block with adaptive backtick fencing
-    \- dispatch_send(encode_bracketed_paste(payload), { open_focus=true, post_focus=true })
+    \- send_dispatch.dispatch_send(terminal_io.encode_bracketed_paste(payload), ...)
          |- [active + ready] -> provider.send(session.handle, text)
-         |- [no active session] -> open_session(args, focus=true)
+         |- [no active session] -> session_lifecycle.open_session(...)
          \- [not ready yet] -> queue + retry loop until ready/timeout
 ```
 
@@ -155,17 +159,17 @@ User runs :CodexMentionFile [path] (or :CodexMentionDirectory [path])
 commands.lua -> codex.mention_file(path_or_nil) (or codex.mention_directory(path_or_nil))
     |
     v
-init.lua mention_file(path) / mention_directory(path)
+init.lua mention_file(path) / mention_directory(path) -> mention module
     |- ensure_setup()
     |- resolve path (arg or current buffer path via %:p / %:p:h)
     |- [missing path] -> log + return false, "current buffer has no file/directory path"
     |- path.to_relative(...)
-    \- dispatch_mention(relative_path)
+    \- mention.dispatch(relative_path)
          |- formatter.format_mention(relative_path)
          |- [active + alive] provider.focus(handle) before prompt capture
          |- capture_terminal_prompt_input() (best effort)
          |- mention_payload = clear_line_sequence + mention_text
-         \- dispatch_send(mention_payload, { open_focus=true, pre_focus=true, command_path="/mention", on_sent=... })
+         \- send_dispatch.dispatch_send(mention_payload, { open_focus=true, pre_focus=true, command_path="/mention", on_sent=... })
               |- on_sent: submit_with_enter_key("/mention")
               \- on_sent: restore captured prompt input via delayed dispatch_send(...)
 ```
@@ -181,12 +185,12 @@ commands.lua -> codex.resume({ last = opts.bang })
     v
 init.lua resume(opts)
     |- ensure_setup()
-    |- session_store.get_active() + get_provider()
+    |- session_lifecycle.get_active_session_and_provider(deps, config)
     |- [active + alive session] -> send_command("resume") (in-process /resume)
     \- [no active/alive session]
          |- args = { "resume" }
          |- if opts.last then args += "--last"
-         \- open_session(args, focus=true)
+         \- session_lifecycle.open_session(deps, config, args, focus=true)
 ```
 
 ### Slash Command Wrappers
@@ -195,7 +199,7 @@ These commands all route through `send_command()`, which normalizes the slash
 command, builds `"/<command>\n"`, and calls:
 
 ```text
-dispatch_send(payload, {
+send_dispatch.dispatch_send(payload, {
   open_focus = true,
   pre_focus = true,
   command_path = "/<command>",

docs/contributing.md

@@ -176,6 +176,8 @@ commit again.
 
 ### Module Structure
 
+Stateless modules use the standard pattern:
+
 ```lua
 local M = {}
 
@@ -188,6 +190,20 @@ function M.public_method() end
 return M
 ```
 
+Modules that need runtime accessors use a `create(opts)` constructor:
+
+```lua
+local M = {}
+
+function M.create(opts)
+  local get_deps = opts.get_deps
+  local function bound_method() ... end
+  return { bound_method = bound_method }
+end
+
+return M
+```
+
 ### Type Annotations
 
 Use EmmyLua annotations for all public functions and types:
@@ -348,9 +364,12 @@ When cutting a new release tag:
 
 ## Adding a New Command
 
-1. **API function** -- Add the public method in `lua/codex/init.lua` with a
-   one-line LuaDoc summary (description first), `---@param`/`---@return`
-   annotations, and an `ensure_setup()` guard.
+1. **API function** -- Add the public method in `lua/codex/init.lua` as a thin
+   delegate with a one-line LuaDoc summary (description first),
+   `---@param`/`---@return` annotations, and an `ensure_setup()` guard. Place
+   the implementation logic in the appropriate extracted module
+   (`session_lifecycle`, `send_dispatch`, or `mention`) if it fits an existing
+   concern; otherwise keep it in `init.lua`.
 2. **User command** -- Register the `:Codex*` command in
    `lua/codex/nvim/commands.lua`, delegating to the API function.
 3. **Unit tests** -- Add test cases in `tests/unit/init_spec.lua` covering the