Dextora

A Python CLI toolkit for diagnosing project setup, dependencies, environment configuration, and common development issues.

Note: Dextora was formerly developed under the initial development name KLYRO.

Dextora helps developers instantly answer three questions:

1. What is wrong with my project setup?
2. Why is it happening?
3. How can I fix it?

Features & Core Capabilities

• Intelligent Project & Framework Classification:
  • Python: Recognizes Django, FastAPI, Flask, and standard Python projects based on declared dependencies and manifests.
  • JavaScript / TypeScript: Recognizes Vue, Nuxt, Svelte, SvelteKit, Angular, Astro, Next.js, React, and generic Node.js projects.
  • Fullstack Combinations: Identifies combined backend/frontend architectures (e.g. Fullstack (FastAPI + Next.js), Fullstack (Django + React)).
  • Preserves base types for generic directories and unrecognized structures.
• Root-Cause Analysis Engine: Deterministically identifies causal relationships among diagnostic findings (e.g. merge conflicts causing parser errors, missing .gitignore causing tracked secrets) and groups them with clear confidence levels (confirmed vs probable) without deleting or altering underlying findings.
• Context-Aware Remediation: Provides exact, safe remediation commands tailored to the detected package manager (pnpm, yarn, bun, npm, poetry, pipenv, pip) and marks complex migrations as requiring manual review.
• Python Environment Verification: Detects standard virtual environments (.venv, venv, env), verifies interpreter executables, checks Python version compatibility (requires-python), and checks site-packages status.
• Dependency Diagnostics: Detects missing lockfiles (Pipfile without Pipfile.lock), orphaned lockfiles (poetry.lock without pyproject.toml), conflicting package managers, duplicate dependencies, and unpinned packages in requirements.txt.
• Environment & Secret Safety: Validates .env variables against .env.example/.env.sample templates without ever reading, logging, or exposing secret values in findings, remediations, or JSON outputs.
• Version Control Diagnostics: Detects Git status, .gitignore presence and coverage, unmerged Git conflict markers (<<<<<<<), and verifies whether sensitive files are tracked by Git.
• JavaScript/TypeScript Diagnostics: Detects package.json syntax errors, flags conflicting lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb), and checks lockfile presence with packageManager field awareness.
• Strict Read-Only Safety: Diagnostic commands never modify scanned files, never execute arbitrary project scripts, never execute suggested remediation commands, and safely bypass ignored directories (.git, node_modules, .venv, dist, build, caches).

Implemented Diagnostic Codes

Installation & Setup

Prerequisites

• Python 3.11 or newer

Local Development Setup (Windows PowerShell)

# 1. Clone or navigate to the repository
cd D:\KLYRO

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate the virtual environment
.\.venv\Scripts\Activate.ps1

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

Once installed, the dextora command is available in your shell. You can also run it directly via python -m dextora.

CLI Usage & Commands

dextora --help

Displays command overview, flags, and usage examples:

dextora --help

dextora --version

Displays installed Dextora version:

dextora --version

dextora doctor

Scans the current working directory:

dextora doctor

dextora doctor <path>

Scans a specific target project without modifying its contents:

dextora doctor C:\Users\dev\my-app

dextora doctor [path] --json

Outputs clean, machine-readable JSON (ideal for CI pipelines and scripts):

dextora doctor --json

dextora doctor [path] --strict

Exits with code 1 if any WARNING or ERROR findings are discovered (default exits 1 on ERROR only).

dextora doctor --strict

dextora init [path]

Initializes a minimal .dextora.toml configuration in the project. Refuses to overwrite existing configuration without --force:

dextora init
# Or overwrite existing:
dextora init --force

Sample Outputs

Terminal Output (dextora doctor)

+------------------------------------------------+
| Dextora v0.1.0 - Developer Diagnostics Toolkit |
| Target:       D:\Projects\sample-app           |
| Project Type: Python                           |
| Checks Run:   6                                |
+------------------------------------------------+

>>> WARNINGS (2)
----------------------------------------
[PY001] No Python virtual environment detected
  Why:      Python projects should use an isolated virtual environment to prevent dependency pollution.
  Evidence: Looked for: .venv, venv, env in project root.
  Fix:      Create a virtual environment with 'python -m venv .venv' and activate it.

[ENV001] Environment template '.env.example' present but '.env' is missing (.env.example)
  Why:      The project provides '.env.example' as an environment template, but no local '.env' file was found.
  Evidence: Template: .env.example
  Fix:      Copy '.env.example' to '.env' and fill in the required local configuration values.

>>> SUCCESSES (1)
----------------------------------------
[STR002] Project manifest detected (pyproject.toml)
  Why:      Identified Python project configuration manifests.
  Evidence: pyproject.toml
  Fix:      No action required.

 Diagnostic Summary
  Severity    Count
  Errors          0
  Warnings        2
  Info            0
  Passed          1

[!] Scan completed with 2 warning(s). Review the suggestions above.

Machine-Readable JSON Output (dextora doctor --json)

{
  "version": "0.1.0",
  "target_path": "D:\\Projects\\sample-app",
  "project_type": "Python",
  "checks_run": 6,
  "summary": {
    "ERROR": 0,
    "WARNING": 2,
    "INFO": 0,
    "SUCCESS": 1
  },
  "findings": [
    {
      "code": "PY001",
      "severity": "WARNING",
      "title": "No Python virtual environment detected",
      "explanation": "Python projects should use an isolated virtual environment to prevent dependency pollution.",
      "evidence": "Looked for: .venv, venv, env in project root.",
      "fix": "Create a virtual environment with 'python -m venv .venv' and activate it.",
      "file_path": null
    },
    {
      "code": "ENV001",
      "severity": "WARNING",
      "title": "Environment template '.env.example' present but '.env' is missing",
      "explanation": "The project provides '.env.example' as an environment template, but no local '.env' file was found.",
      "evidence": "Template: .env.example",
      "fix": "Copy '.env.example' to '.env' and fill in the required local configuration values.",
      "file_path": ".env.example"
    },
    {
      "code": "STR002",
      "severity": "SUCCESS",
      "title": "Project manifest detected",
      "explanation": "Identified Python project configuration manifests.",
      "evidence": "pyproject.toml",
      "fix": "No action required.",
      "file_path": "pyproject.toml"
    }
  ]
}

Supported Frameworks & Ecosystems

Dextora uses declared dependencies, manifests, and lockfiles to reliably classify projects:

Known Limitations

• Offline-Only Analysis: Dextora performs static local analysis and does not connect to PyPI, npm, or external networks to resolve transitive dependency trees.
• Root-Level Monorepos: Dextora primarily targets the root project directory and immediate components. Deeply nested workspace packages (e.g., Turborepo or nested multi-package monorepos) are classified from their top-level manifest rather than traversed independently.
• Static Pattern Matching: Environment verification checks .env and .env.example keys; dynamic environment resolution injected at runtime by remote secret managers (e.g. AWS Secrets Manager, HashiCorp Vault) is outside Dextora's local static scope.

Safety Model

1. Read-Only: Diagnostic commands (doctor) never alter project files or directory structure.
2. Secret Privacy: Secret values from .env files are never parsed into memory for display, logged, or included in diagnostic evidence. Only variable names are compared.
3. No Execution: Project scripts, hooks, or package installation commands are never executed during scanning.
4. Filesystem Boundaries: Directory traversal does not follow symlinks outside target root, and skips directories known to contain large generated files (.git, node_modules, .venv, caches).
5. Deterministic: Diagnostics produce predictable, deterministic findings based strictly on file presence and parsed content.

Development & Testing

Running Tests

Run the full pytest suite:

.\.venv\Scripts\python.exe -m pytest -v

Building the Package

To build source distribution (sdist) and binary wheel (wheel):

.\.venv\Scripts\python.exe -m build

Artifacts are produced in the dist/ directory.

Community & Contributing

• Contributing: Please review CONTRIBUTING.md for contribution workflows and development setup.
• Changelog: See CHANGELOG.md for release notes.
• Security Policy: See SECURITY.md for vulnerability reporting procedures.
• License: MIT License. See LICENSE for details.