How greyhoundforty/tengingarstjori works
Project Type and Purpose
• Tengingarstjóri is a standalone Python CLI/TUI application (a command-line SSH connection manager) packaged as a library for import and as an executable tg command.
• Purpose: allow users to manage SSH connections (add, list, remove, show, tunnel, proxy-jump) via a clean CLI interface while storing state in a managed SSH config file and a JSON data store.
File Structure Analysis
• Top-level:
• Configuration and metadata (pyproject.toml, setup files, workflows, scripts, docs)
• main.py – CLI entrypoint
• src/ – application code plus top-level cli.py, config_manager.py, models.py, exceptions.py, and setup.py
• src/tengingarstjori/ – the same modules under the package namespace (real library code)
• tests/ – unit and integration tests for each module and feature
• scripts/ – automation: build, test, formatting, packaging
• Architectural patterns:
• Layered structure: CLI layer → domain/API layer → persistence layer → external systems
• Separation of concerns: cli.py handles parsing; config_manager.py handles business logic; models.py defines data objects; file I/O and SSH external calls are encapsulated in the manager.
README Insights
• Core architecture described in README under “Architecture”:
1. Managed SSH config file (~/.ssh/config.tengingarstjori)
2. Inclusion into main SSH config
3. Persistent JSON store at ~/.tengingarstjori/connections.json
4. Non-invasive integration
• Features list highlights key components: CLI commands, proxy-jump, port forwarding, JSON output, Python API.
a. Main Components
• User Terminal (shell)
• CLI Interface (tg / main.py)
• Application Layer (tengingarstjori.cli → tengingarstjori.config_manager)
• Data Models (SSHConnection, settings, exceptions)
• Persistence Layer
• JSON Store (~/.tengingarstjori/connections.json)
• Managed SSH Config File (~/.ssh/config.tengingarstjori)
• External Systems
• Native SSH binary (ssh)
• User’s original SSH config (~/.ssh/config)
b. Relationships & Interactions
• User invokes tg <command> → CLI layer parses command → calls methods on SSHConfigManager
• Manager reads/writes the JSON store and updates the managed SSH config file
• On tg connect (or underlying ssh <host>), CLI may shell out to the SSH binary, passing host alias
• Backup and reset commands interact with user’s original config (create backups, restore)
c. Architectural Patterns & Principles
• Layering: clear CLI vs. business logic vs. persistence
• Single Responsibility: each module has one role (parsing, data validation, I/O)
• Non-invasive integration: isolation of managed config
• Extensibility: Python API for programmatic use
d. Key Technologies & Libraries
• Python standard library: argparse or click, json, pathlib, subprocess
• Packaging: pyproject.toml, setuptools, wheel
• Testing: pytest, bespoke test scripts, CI workflows (.github/workflows)
• Linting & formatting: flake8, black, pre-commit
Detailed Capture of Architectural Elements
• Both the packaging/deployment side (PyPI package, CI workflows) and the runtime side (CLI & library).
• Separate the code modules into logical layers.
• Avoid over-segmenting; focus on the main 5–7 components listed above and their interactions.