How hbisneto/supernanno works
1. Entry points and runtime
- The package starts through supernanno/__main__.py and supernanno/app.py, which bootstrap the Textual TUI application.
- Command-line parsing lives under supernanno/cli/, so startup decisions like file path, read-only mode, line jump, and search seed happen before the UI is mounted.
2. Top-level architecture
- The repository is organized into a clear split between UI, event handling, services, core business logic, and search/state subsystems.
- The core design is service-oriented and event-driven: widgets emit events, events are handled by dedicated modules, and the handlers delegate into services/core rather than embedding logic in UI components.
3. Application façade
- supernanno/services/app_context.py is the central boundary object.
- It acts as the shared access point for configuration, logging, error handling, session state, file operations, and other cross-cutting concerns, reducing direct coupling between UI widgets and lower-level logic.
4. UI layer
- supernanno/ui/ contains the Textual widgets and layouts: editor layout, search bar, startup view, and settings screen.
- style.tcss defines the terminal styling, while ui/bindings.py centralizes keyboard shortcuts.
- This layer is presentation-focused; it routes user actions outward instead of owning business rules.
5. Event-driven interaction flow
- User input is translated into Textual events under supernanno/events/ such as key presses, button clicks, input changes, mount/unmount, and file-tree selection.
- These events are handled by focused modules in supernanno/handlers/ for high-level actions like opening files, quitting, and toggling the sidebar.
- This creates a one-way flow: UI → event → handler → service/core logic → UI/status update.
6. Core editing and file operations
- supernanno/core/editor.py and supernanno/core/file_manager.py are the main editing backend.
- FileManager owns file I/O and backup behavior; the README indicates atomic save semantics via temp-file-then-rename and .bak creation before overwrite.
- core/status.py, core/logger.py, and core/structured_logger.py support editor feedback and structured observability, while remaining separate from the widget tree.
7. Search subsystem
- Search is isolated under supernanno/search/ and uses a strategy pattern.
- registry.py selects a strategy at runtime, strategies.py implements literal/case-sensitive/regex modes, engine.py performs matching, and controller.py coordinates UI actions and search state.
- Search state is tracked separately in supernanno/states/search.py, which keeps search mode and results distinct from the editor buffer.
8. Configuration and settings
- The app consumes two config layers: declarative .supernannorc parsing and structured config.json runtime settings.
- supernanno/services/rc_parser.py, config_manager.py, and config_applier.py load and merge settings; paths.py resolves platform-specific config locations.
- The README’s async watcher implies config changes can be hot-reloaded, so config is a live input to the app rather than a startup-only concern.
- supernanno/ui/settings/screen.py exposes that configuration through the UI.
9. Session and startup behavior
- supernanno/services/session_manager.py persists editor session metadata such as the last opened file.
- On launch, startup flow can restore the previous file/session and optionally show the startup view (ui/startup_view.py) before or alongside editing.
- This is a local persistence path, not a network-backed sync system.
10. Observability and diagnostics
- Logging and error handling are first-class subsystems in supernanno/services/log_service.py, error_service.py, and issue_service.py.
- Errors are classified, given correlation IDs, logged as structured events, and surfaced through the status bar.
- The diagnostic flow can generate a GitHub issue report, but that is an explicit user action rather than automatic telemetry.
11. State management
- supernanno/states/base.py and the specialized state modules capture app-level workflow state that should outlive a single widget callback.
- This keeps transient UI state, search state, and editor/session state separated so Textual widgets remain relatively thin.
12. External technology boundaries
- The app is a Python terminal application built on Textual and uses Tree-sitter for syntax parsing/highlighting, with Pygments as fallback for unsupported languages.
- It is primarily offline/local-first; the only notable external integration is optional GitHub issue formatting through the diagnostic service.
- Tests in supernanno/tests/ focus on core/services behavior rather than depending heavily on the widget tree, reinforcing the separation between presentation and logic.
Main entry points: app.py App · layout.py Layout · handlers Action handlers · app_context.py App context
Components 22
Entry & CLI
Process startup and argument parsing
- Startup · Launches the Textual app
supernanno/__main__.py - App · Bootstraps the application and wires subsystems
supernanno/app.py - CLI parser · Parses file, mode, and startup options
supernanno/cli/parser.py
UI layer
Textual widgets, layouts, bindings, and screens
- Layout · Main editor arrangement and screen composition
supernanno/ui/layout.py - Search bar · Search input and query controls
supernanno/ui/search_bar.py - Startup view · Initial landing and file selection view
supernanno/ui/startup_view.py - Settings screen · Configuration editing interface
supernanno/ui/settings/screen.py - Bindings · Keyboard shortcut definitions
supernanno/ui/bindings.py
Events
UI-generated interaction events
- UI events · Key, input, mount, and selection events
supernanno/events
Handlers
High-level action routing
- Action handlers · File, quit, and sidebar actions
supernanno/handlers
Services
Cross-cutting app services and configuration
- App context · Shared access to config, logging, errors, session, and I/O
supernanno/services/app_context.py - Config stack · RC parsing, config merging, path resolution, and application
supernanno/services/config_manager.py - Session manager · Persists local session metadata such as last file
supernanno/services/session_manager.py - Diagnostics · Logging, structured errors, and issue reporting
supernanno/services/error_service.py
Core
Editing, file I/O, and observability primitives
- Editor core · Editing state and buffer operations
supernanno/core/editor.py - File manager · Atomic saves, backups, and file access
supernanno/core/file_manager.py - Status logs · Status messaging and structured logging support
supernanno/core/status.py
Search
Search strategies and coordination
- Search ctrl · Coordinates search actions and search state
supernanno/search/controller.py - Search engine · Executes query matching against content
supernanno/search/engine.py - Search modes · Selects literal, case-sensitive, and regex strategies
supernanno/search/registry.py
State
App and search state models
- Search state · Tracks search mode, query, and results
supernanno/states/search.py - App state · General workflow state shared across widgets
supernanno/states/base.py
Connections 27
- Startup → CLI parser: parse args · Startup reads command-line options before UI mount
- Startup → App: launch · Entrypoint starts the application runtime
- CLI parser → App: startup config · CLI decisions feed app initialization
- App → App context: build context · App creates the shared boundary object
- App context → Config stack: load config · Context exposes configuration services
- App context → Session manager: restore session · Context provides persisted session data
- App context → Diagnostics: diagnose · Context centralizes logging and error handling
- App → Layout: mount UI · App composes the main Textual layout
- App → Startup view: startup view · Initial screen can be shown on launch
- App → Settings screen: settings · Settings screen is part of the UI surface
- Layout → Search bar: contains · Layout includes the search interface
- Layout → Bindings: shortcuts · Layout uses centralized key bindings
- Layout → UI events: emit events · Widgets translate input into events
- Search bar → UI events: submit input · Search input emits interaction events
- Startup view → UI events: select file · Startup interactions become events
- UI events → Action handlers: dispatch · Events are handled by action modules
- Action handlers → Editor core: edit flow · Handlers coordinate editor actions
- Action handlers → File manager: file flow · Handlers delegate file operations to file manager
- Action handlers → Search ctrl: search flow · Handlers invoke search orchestration
- Editor core → File manager: persist · Editor uses file I/O for loading and saving
- Editor core → Status logs: status · Editor reports progress and issues
- Diagnostics → Status logs: surface errors · Diagnostics feed structured status and logs
- Search ctrl → Search modes: choose mode · Controller selects the runtime search strategy
- Search ctrl → Search engine: run query · Controller delegates matching work to the engine
- Search ctrl → Search state: track results · Search workflow state is maintained separately
- Search engine → Search state: update state · Matches and mode changes are reflected in state
- App → App state: shared state · Application workflow state is stored centrally