Nexterm

The Local Developer Operating System CLI.
Address your software projects by name across workspaces, automate environment setup, defend repositories with pre-push hooks, edit commands with terminal line controls, and release packages securely.

🚀 Installation

Install the package directly from PyPI:

pip install nexterm

This installs the primary CLI executable nexterm, along with aliases (workspace, worksapce, developeros, work).

Verify Installation

nexterm --version
nexterm --help

⚡ Quick Start

# 1. Launch the interactive DeveloperOS shell
workspace

# 2. Index your workspace directories
workspace scan ~/code

# 3. Search projects by name, language, or framework
workspace find react
workspace find --language python

# 4. Launch your editor and track usage
workspace open portfolio

# 5. Auto-bootstrap project dependencies, environment, stack & browser
workspace start portfolio

# 6. Diagnose toolchains, missing .env files, and port conflicts
workspace doctor --fix

# 7. Install pre-push Git hook repository defense
workspace guardian install-hook

# 8. Run pre-release validation & artifact secret scan
workspace release check

🔥 Key Subsystems & Features

1. Interactive Terminal Shell & Line Editor Subsystem

Launch workspace to enter an interactive CWD prompt supporting native OS commands (ls, cd, git, npm, python, docker) alongside DeveloperOS commands.

Line Editing Keyboard Shortcuts

2. Context-Aware Tab Completion Engine

DeveloperOS features 7 intelligent completion providers triggered by <Tab>:

1. Top-Level Commands: start, open, doctor, find, scan, guardian, release, etc.
2. Project Names: Auto-completes indexed project names when typing start, open, doctor, fix.
3. PATH Executables: Completes binary executables available on your system PATH.
4. Native Tool Subcommands: Rich subcommands for git, docker, npm, pip, python, node, cargo.
5. Subcommand Options: Options for guardian (check, install-hook, remove-hook, status), release (check, build, verify), stack, tag, pref, daemon.
6. Directory-Only Completion: Smart filtering for cd <dir>.
7. Filesystem Completion: Path completion for file arguments.

3. Pre-Push Guardian Subsystem (workspace guardian)

Blocks broken, insecure, unformatted, or incomplete code from reaching remote branches before git push executes.

# Install the Git pre-push hook into .git/hooks/pre-push
workspace guardian install-hook

# Check hook installation status
workspace guardian status

# Run full local pre-push validation engine manually
workspace guardian check

# Remove Git pre-push hook
workspace guardian remove-hook

Pre-Push Verification Pipeline:

• Git Hygiene: Validates .gitignore presence and checks for untracked secret files (.env, *.db, *.key, *.pem, *.log, id_rsa).
• Diff Secret Scanner: Scans diff additions and changed files for API keys, private keys (id_rsa, -----BEGIN PRIVATE KEY-----), GitHub tokens (ghp_), PyPI tokens (pypi-), and Slack bot tokens (xoxb).
• Dependency & Version Validation: Checks pyproject.toml syntax and verifies code-to-package version alignment.
• Automated Test Suite: Executes pytest unit test suite.
• Build & Metadata Gate: Executes python -m build and twine check dist/*.
• Artifact Secret Content Scanner: Scans built .whl and .tar.gz for secrets or forbidden files.
• Clean Venv Smoke Test: Installs built wheel into an isolated temporary virtual environment and verifies workspace --version / workspace --help.
• Emergency Bypass: Pass SKIP_GUARDIAN=1 git push or git push --no-verify to bypass with automated logging.

4. PyPI Release Subsystem (workspace release)

Professional release automation complying with PEP 517/518 and GitHub Actions PyPI Trusted Publishing (OIDC).

# Run 7-stage pre-release check locally
workspace release check

# Build wheel and sdist packages into dist/
workspace release build

# Validate metadata, scan artifact content secrets, and test clean venv installation
workspace release verify

Security Guarantee:

• ZERO PyPI Tokens Required: Uses GitHub Actions OpenID Connect (id-token: write) via pypa/gh-action-pypi-publish@release/v1. Zero passwords or long-lived secrets in source code, .env, configs, or GitHub secrets.

5. Structured Error UX Subsystem (workspace errors)

Replaces cluttered error tracebacks with human-readable diagnostic cards answering:

• WHAT failed?
• WHERE did it fail?
• WHY did it fail?
• WHAT was the exit code?
• WHAT actionable steps can the user take next?

Includes automatic secret redaction (SecretRedactor) and SQLite history logging viewable via workspace errors.

6. Doctor Diagnostics & Repair Subsystem (workspace doctor)

Diagnoses toolchain issues, port conflicts, missing .env files, and database corruption, offering automated repair via workspace doctor --fix.

7. Autonomous Local AI & Fix Agent (workspace ai / workspace fix)

Local hardware profiler detecting CPU, RAM, GPU, and disk specs to recommend and download GGUF/Ollama model configurations for local offline AI assistance:

workspace ai install
workspace ask "How do I set up a PostgreSQL connection pool in Python?"
workspace explain portfolio
workspace fix portfolio

🛠️ CLI Command Reference

💻 Development & Contributing

Setup Development Environment

# Clone the repository
git clone https://github.com/Mr-Anonymous-Guy/Nexterm.git
cd Nexterm

# Install in editable mode with development dependencies
pip install -e .[dev]

Running Test Suite

# Run full unit test suite (200+ tests)
pytest -v

# Run specific test modules
pytest tests/test_guardian.py -v
pytest tests/test_release.py -v
pytest tests/test_terminal.py -v
pytest tests/test_errors.py -v
pytest tests/test_core.py -v

Running Pre-Push Guardian & Pre-Release Checks

python scripts/pre_push_guardian.py
python scripts/release_check.py

For full release architecture documentation, see Docs/PYPI_RELEASE_ARCHITECTURE.md and Docs/GIT_GUARDIAN_ARCHITECTURE.md.

📄 License

Distributed under the MIT License. See LICENSE for details.