ocn-cli 1.0.0__tar.gz

ocn_cli-1.0.0/.github/RELEASE_TEMPLATE.md

@@ -0,0 +1,57 @@
+# OCN CLI Release vX.Y.Z
+
+## What's New
+
+<!-- Describe the main features/fixes in this release -->
+
+### New Features
+- Feature 1
+- Feature 2
+
+### Bug Fixes
+- Fix 1
+- Fix 2
+
+### Improvements
+- Improvement 1
+- Improvement 2
+
+---
+
+## Installation
+
+Install or upgrade to this version:
+
+```bash
+pip install --upgrade ocn-cli
+```
+
+Verify installation:
+```bash
+ocn-cli --version
+```
+
+Should show: `OCN CLI version X.Y.Z`
+
+---
+
+## Breaking Changes
+
+<!-- List any breaking changes that require user action -->
+
+- None
+
+---
+
+## Documentation
+
+- [README](https://github.com/your-org/ocn/blob/main/cli/README.md)
+- [Diagnostics Guide](https://github.com/your-org/ocn/blob/main/cli/DIAGNOSTICS.md)
+- [Changelog](https://github.com/your-org/ocn/blob/main/cli/CHANGELOG.md)
+
+---
+
+## Full Changelog
+
+See [CHANGELOG.md](https://github.com/your-org/ocn/blob/main/cli/CHANGELOG.md) for complete version history.
+

ocn_cli-1.0.0/AGENTS.md

@@ -0,0 +1,270 @@
+# OCN CLI - Agent Guidelines
+
+This document provides guidelines for AI agents working on the OCN CLI diagnostic tool.
+
+## Project Overview
+
+The OCN CLI is a Python-based command-line interface for remote diagnostics of OCN servers. It provides:
+- Secure SSH connections with key-based authentication
+- Interactive shell with history, autocomplete, and syntax highlighting
+- Built-in helper commands for common diagnostic operations
+- Cross-platform compatibility (Windows, macOS, Linux)
+
+## Tech Stack
+
+- **Python 3.9+** - Modern Python with type hints
+- **Typer** - CLI framework with automatic help generation
+- **Paramiko** - SSH client library
+- **prompt_toolkit** - Interactive shell with REPL features
+- **Rich** - Terminal output formatting
+
+## Architecture
+
+```
+ocn_cli/
+├── cli.py              # Main entry point (Typer app)
+├── version.py          # Version metadata
+├── auth/               # Authentication layer
+│   └── key_manager.py      # SSH key loading and validation
+├── ssh/                # SSH connection layer
+│   ├── connection.py       # SSH connection management
+│   ├── command_executor.py # Remote command execution
+│   └── errors.py           # SSH error types
+├── shell/              # Interactive shell layer
+│   ├── interactive.py      # Main REPL loop
+│   ├── completer.py        # Autocomplete
+│   ├── highlighter.py      # Syntax highlighting
+│   └── history.py          # Command history
+├── commands/           # Helper commands layer
+│   ├── base.py             # Command protocol
+│   ├── registry.py         # Command registry
+│   ├── help.py             # Help command
+│   ├── status.py           # Status command
+│   └── diagnose.py         # Comprehensive diagnostics command
+├── diagnostics/        # Diagnostics framework
+│   ├── base.py             # Base diagnostic check classes
+│   ├── runner.py           # Diagnostic execution engine
+│   ├── result.py           # Result data structures
+│   ├── formatter.py        # Report formatters (text, JSON, HTML)
+│   └── checks/             # Individual diagnostic checks
+│       ├── network.py          # Network connectivity checks
+│       ├── dns.py              # DNS resolution checks
+│       ├── keygen.py           # keygen.sh accessibility
+│       ├── docker_install.py   # Docker installation validation
+│       ├── containers.py       # Container status checks
+│       ├── dpkg_lock.py        # dpkg lock detection
+│       ├── resources.py        # CPU, memory, disk checks
+│       ├── services.py         # Critical service checks
+│       ├── logs.py             # Log file size monitoring
+│       └── time_sync.py        # NTP time synchronization
+├── offline/            # Offline update support
+│   ├── uploader.py         # SFTP file upload with progress
+│   └── validator.py        # Package validation
+├── ui/                 # User interface layer
+│   ├── messages.py         # Message templates
+│   └── formatters.py       # Rich formatting
+└── utils/              # Utilities layer
+    ├── platform.py         # Cross-platform helpers
+    └── security.py         # Security utilities
+```
+
+## Code Conventions
+
+### Type Hints
+- **Always use type hints** for all function parameters and return types
+- Use `from typing import` for complex types (List, Dict, Optional, etc.)
+- Use modern syntax where possible: `list[str]` instead of `List[str]` (Python 3.11+)
+
+### Error Handling
+- Use specific exception types from `ssh/errors.py`
+- Always provide helpful error messages with troubleshooting hints
+- Never expose sensitive data (passwords, keys) in error messages
+
+### Security
+- Never log or persist credentials to disk
+- Validate file permissions on SSH keys
+- Use context managers for automatic cleanup
+
+### UI/UX
+- Use Rich for all terminal output (colors, tables, panels)
+- Keep messages user-friendly and actionable
+- Provide troubleshooting hints for all errors
+- Use icons/emojis sparingly for visual clarity
+
+## Development Workflow
+
+### Local Testing
+
+```bash
+# Install in development mode
+pip install -e .
+
+# Run directly
+ocn-cli --help
+
+# Or as module
+python -m ocn_cli --help
+```
+
+### Adding New Helper Commands
+
+1. Create new command class in `commands/`
+2. Implement `HelperCommand` protocol:
+   - `name` property
+   - `description` property
+   - `aliases` property
+   - `execute(executor, args)` method
+3. Register in `commands/__init__.py`
+
+Example:
+
+```python
+class MyCommand:
+    @property
+    def name(self) -> str:
+        return "mycommand"
+    
+    @property
+    def description(self) -> str:
+        return "Description of what it does"
+    
+    @property
+    def aliases(self) -> List[str]:
+        return ["mc", "mycmd"]
+    
+    def execute(self, executor: CommandExecutor, args: List[str]) -> str:
+        result = executor.execute("remote command")
+        return f"Output: {result.stdout}"
+```
+
+### Adding New Diagnostic Checks
+
+1. Create new check class in `diagnostics/checks/`
+2. Inherit from `DiagnosticCheck` abstract base class
+3. Implement required methods:
+   - `name`, `category`, `severity` properties
+   - `async def execute(self) -> CheckResult`
+4. Register in `diagnostics/runner.py` → `register_all_checks()`
+
+Example:
+
+```python
+from ocn_cli.diagnostics.base import DiagnosticCheck, CheckResult, CheckSeverity
+
+class MyDiagnosticCheck(DiagnosticCheck):
+    def __init__(self, executor: CommandExecutor) -> None:
+        self.executor = executor
+    
+    @property
+    def name(self) -> str:
+        return "my_check"
+    
+    @property
+    def category(self) -> str:
+        return "system"
+    
+    @property
+    def severity(self) -> CheckSeverity:
+        return CheckSeverity.WARNING
+    
+    async def execute(self) -> CheckResult:
+        result = self.executor.execute("some command", stream=False)
+        
+        if result.exit_code != 0:
+            return CheckResult(
+                check_name=self.name,
+                category=self.category,
+                passed=False,
+                severity=self.severity,
+                message="Check failed",
+                remediation=["How to fix this issue"]
+            )
+        
+        return CheckResult(
+            check_name=self.name,
+            category=self.category,
+            passed=True,
+            severity=self.severity,
+            message="Check passed"
+        )
+```
+
+### SSH Key Management
+
+The CLI uses standard SSH key-based authentication:
+
+1. Users provide their SSH private key via `--key` argument
+2. KeyManager validates the key format and permissions
+3. Paramiko loads the key (supports RSA, Ed25519, ECDSA, DSS)
+4. Key must be authorized on the OCN server's `~/.ssh/authorized_keys`
+
+## Testing
+
+- Use `pytest` for unit and integration tests
+- Mock SSH connections for unit tests
+- Test error paths and edge cases
+- Verify cross-platform compatibility
+
+## Common Tasks
+
+### Update Version
+
+Edit `ocn_cli/version.py`:
+```python
+__version__ = "1.1.0"
+```
+
+### Add New Dependency
+
+1. Add to `pyproject.toml` dependencies array
+2. Add to `requirements.txt` with pinned version
+3. Update documentation if needed
+
+### Debug Issues
+
+- Check `~/.cursor/projects/.../terminals/` for command output
+- Use Rich console for debug prints: `console.print("[debug]...")`
+- Test with verbose SSH logging if needed
+
+### Offline Update Support
+
+The CLI supports updating offline OCN servers:
+
+1. Upload update packages via SFTP
+2. Validate package structure
+3. Apply updates without internet
+4. Based on existing `update.sh` workflow
+
+**Phase 1 Limitations:**
+- Docker CE must already be installed
+- No Docker migration in offline mode
+- No system package updates
+
+**See:** `OFFLINE_UPDATES.md` for usage guide
+
+## Future Enhancements
+
+Planned features for future versions:
+- Offline Docker migration support
+- System package updates offline
+- Configuration file support for server profiles
+- Session recording and playback
+- Remote script execution
+- Multi-server management
+- Passphrase-protected key support
+
+## Rules for AI Agents
+
+1. **Preserve existing patterns** - Follow the established architecture and code style
+2. **Type everything** - All functions must have type hints
+3. **Security first** - Never compromise security for convenience
+4. **User experience** - Error messages must be helpful and actionable
+5. **Cross-platform** - Test changes on all supported platforms
+6. **No breaking changes** - Maintain backward compatibility
+7. **Document changes** - Update README and CHANGELOG for user-facing changes
+
+## Contact
+
+For questions or issues:
+- GitHub: https://github.com/your-org/ocn/issues
+- Documentation: /Users/max/Documents/GitHub/ocn/cli/

ocn_cli-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Strato Automation Software Development Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

ocn_cli-1.0.0/MANIFEST.in

@@ -0,0 +1,13 @@
+# Include resources directory
+recursive-include resources *
+
+# Include documentation
+include README.md
+include LICENSE
+
+# Exclude development files
+exclude .gitignore
+recursive-exclude tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+