Metadata-Version: 2.2
Name: vishwajeet-12
Version: 1.0.0
Summary: A lightweight, Python-friendly command-line toolkit for personal development.
Author: Vishwajeet More
License: MIT License
        
        Copyright (c) 2026 Vishwajeet More
        
        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.
        
        
Keywords: cli,developer-tools,diagnostics,utilities,vishwajeet
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: complete
Requires-Dist: typer>=0.9.0; extra == "complete"
Requires-Dist: rich>=13.0.0; extra == "complete"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# Vishwajeet (`vishwajeet-12`)

> A lightweight, Python-friendly command-line toolkit for personal development.

**Vishwajeet** is a fast, local-first command-line developer toolkit created by **Vishwajeet More**. It combines practical day-to-day developer utilities and read-only environment diagnostics with a clean terminal experience and witty Gen-Z + Hinglish dark developer humor.

- **Distribution package name (pip):** `vishwajeet-12`
- **Terminal command:** `vishwajeet` (also available as `vishwajeet-12`)
- **Python import name:** `vishwajeet`
- **Offline & private:** Requires no account, API key, database, remote server, or internet connection during operation.

---

## Features

1. **Default Signature Greeting (`vishwajeet`)** — A concise terminal greeting (`:) Greeting from Vishwajeet More.`) and quick-start pointer.
2. **Developer Profile (`vishwajeet about`)** — A witty 4-line developer bio for Vishwajeet More (`"Badmosh"`), covering Lionel Messi, cooking, and dark tech humor, with optional raw JSON output (`--json`).
3. **Environment Diagnostics (`vishwajeet doctor`)** — A strictly read-only inspection of your operating system, Python runtime, active virtual environment, current directory, Git repository status, and installed tools (`pip`, `Git`, `Node.js`, `npm`).
4. **Developer Utilities (`vishwajeet utils`)**:
   - `uuid`: Explains what a UUID v4 does in two simple lines and generates a unique RFC 4122 UUID v4 offline.
   - `password`: Generate cryptographically random passwords using Python's `secrets` module.
   - `json`: Validate JSON files in read-only mode with exact line and column error reporting.
5. **Safe Python Code Checker (`vishwajeet clean`)** — Inspect a Python file in read-only mode for trailing whitespace, long lines, missing final newline, and mixed tabs/spaces without ever importing, executing, or modifying the file.

---

## Requirements

- **Python:** 3.9 or newer (tested on Python 3.12)
- **Runtime dependencies:**
  - `typer >= 0.9.0`
  - `rich >= 13.0.0`
- **Supported terminals:** Windows PowerShell, Windows Command Prompt, Windows Terminal, Linux shells (`bash`, `zsh`), and macOS Terminal. Output uses clean plain text without emojis or fragile box-drawing characters.

---

## Installation

### 1. Installing from Local Source (Current Checkout)

Before the package is published to PyPI, install it directly from this project directory inside a virtual environment:

**Windows PowerShell:**

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[complete]"
```

**Linux / macOS:**

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[complete]"
```

### 2. Installing from PyPI (After Public Release)

Once you have published the package to the Python Package Index (see [PUBLISHING.md](PUBLISHING.md); **not published automatically**), anyone can install it via `pip`:

```powershell
python -m pip install vishwajeet-12
```

### Verifying Installation (Post-Install Step)

For security and reliability, standard `pip` installations do not execute arbitrary Python code or print custom post-install banners during `pip install`. After `pip` reports `Successfully installed vishwajeet-12-1.0.0`, run `vishwajeet` to verify the installation and view the greeting:

```powershell
vishwajeet
```

Expected output:

```text
:) Greeting from Vishwajeet More.

Built for developers who make sense.

Run 'vishwajeet --help' to explore the toolkit.
```

You can also invoke the CLI via Python's module runner:

```powershell
python -m vishwajeet
```

---

## Command Reference

| Command | Description |
| :--- | :--- |
| `vishwajeet` | Display the default greeting from Vishwajeet. |
| `vishwajeet --help` / `vishwajeet -h` | Show top-level help and command examples. |
| `vishwajeet help [command]` | Display help for the CLI or a specific subcommand. |
| `vishwajeet --version` / `-V` | Display the installed package version. |
| `vishwajeet about` | Display Vishwajeet More's developer profile. |
| `vishwajeet about --json` | Output the developer profile as valid JSON only. |
| `vishwajeet doctor` | Run read-only local developer environment diagnostics. |
| `vishwajeet utils --help` | Show help and examples for all utility subcommands. |
| `vishwajeet utils uuid` | Generate a random UUID v4. |
| `vishwajeet utils password` | Generate a cryptographically secure password. |
| `vishwajeet utils json <file>` | Validate a JSON file and report line/column on error. |
| `vishwajeet utils base64 encode <text>` | Encode UTF-8 text into standard Base64. |
| `vishwajeet utils base64 decode <text>` | Strictly validate and decode Base64 into UTF-8 text. |
| `vishwajeet clean <file>` | Check a Python file for formatting issues in read-only mode. |

---

## Usage Examples and Feature Guide

### 1. Default Greeting and Help

```powershell
vishwajeet
vishwajeet --help
vishwajeet -h
vishwajeet help
vishwajeet help utils
```

### 2. Developer Profile (`about`)

```powershell
vishwajeet about
```

Output:

```text
ABOUT VISHWAJEET

Vishwajeet More -- known in local commit logs simply as "Badmosh" (pura menace in production).
Die-hard Lionel Messi fan who loves cooking -- whether it's a spicy 2 AM meal in the kitchen or cooking the prod server until it screams.
Treats code like a toxic situationship: gaslights the compiler, forces a push when it says no, and casually kills all orphan processes-- wait, we are still talking about Linux, right?
Writes f*cking elite code by day, fixes one bug by night, and spawns three new ones just to feel something. Scene pura badmosh hai.
```

Machine-readable JSON output:

```powershell
vishwajeet about --json
```

### 3. Developer Environment Diagnostics (`doctor`)

```powershell
vishwajeet doctor
```

**What `vishwajeet doctor` checks and why:**

- **Operating system & platform:** Identifies OS-specific path and process behavior.
- **Python version, implementation & executable:** Confirms which Python interpreter is running your commands.
- **Installation prefix & virtual environment:** Verifies whether your project is isolated in a virtual environment or using the global interpreter.
- **Current directory & Git repository status:** Confirms your working directory and whether `.git` version control metadata is active.
- **Development tools (`pip`, `Git`, `Node.js`, `npm`):** Probes tool versions safely with argument lists (`shell=False`) and a 5-second timeout. Optional tools like `Node.js` and `npm` are reported as `Not found (optional)` if absent rather than treating your environment as broken.

`vishwajeet doctor` is strictly read-only: it never modifies files, installs packages, reads secrets, or prints environment variables.

### 4. Practical Developer Utilities (`utils`)

#### UUID Generation

```powershell
vishwajeet utils uuid
```

Output:

```text
Generates a unique 128-bit random ID (UUID v4) for databases, APIs, or test data.
Created locally offline so every ID is unique and ready to use right away.

Generated UUID:
9f4e2a31-1234-4567-89ab-123456789abc
```

#### Password Generation and Security Considerations

```powershell
vishwajeet utils password
```

- Uses Python's cryptographically strong `secrets` module (`secrets.choice` and `secrets.SystemRandom`), never `random.random()`.
- Supports lengths from `8` to `128` characters (default: `16`).
- Guarantees at least one character from each enabled character category (`uppercase`, `lowercase`, `digits`, `symbols`).
- **Security Note:** The generated password is displayed directly in your terminal output. It may remain visible on screen, in terminal scrollback history, or in screen recordings. Clear your terminal after copying the password into a password manager.

#### JSON Validation

```powershell
vishwajeet utils json config.json
```

- Reads the target file as UTF-8 and parses it with Python's standard `json` module.
- Never modifies or executes any content in the file.
- Returns exit code `0` for valid JSON and exit code `1` with the exact line and column number when syntax validation fails:

```text
Checking JSON: config.json

Result: Invalid JSON.
Error at line 4, column 1: Expecting value
```

#### Base64 Encoding and Decoding

```powershell
vishwajeet utils base64 encode "hello world"
# Output: aGVsbG8gd29ybGQ=

vishwajeet utils base64 decode "aGVsbG8gd29ybGQ="
# Output: hello world
```

- Supports full UTF-8 text.
- Strictly validates Base64 alphabet characters, length multiples of 4, canonical padding bits, and valid UTF-8 output.
- **Important:** Base64 is a binary-to-text encoding format for transport compatibility; it is **not** encryption or a security mechanism.

### 5. Safe Python Source-Code Checker (`clean`)

```powershell
vishwajeet clean app.py
vishwajeet clean app.py --max-line-length 100
```

Example output when issues are found:

```text
Checking: app.py

Line 12 [WARNING]: Trailing whitespace.
Line 19 [WARNING]: Line exceeds 100 characters (114 > 100).

Summary:
2 issues found (0 errors, 2 warnings).

No files were modified.
```

**Checks performed:**
- Trailing whitespace (`[WARNING]`).
- Lines exceeding `--max-line-length` (default `100`, `[WARNING]`).
- Missing final newline at the end of the file (`[WARNING]`).
- Mixed spaces and tabs on the same indentation line (`[ERROR]`) and inconsistent tab vs. space indentation across lines (`[WARNING]`).
- Empty files, missing paths, directories passed instead of files, and invalid UTF-8 encodings.

**Scope and Limitations:**
- Strictly **read-only** in Version 1.0 (there is no `--fix` flag that rewrites user code).
- Never imports, executes, or calls `eval()`/`exec()` on the inspected Python file.
- Designed as a lightweight single-file sanity check, not a replacement for full AST static analyzers or formatters such as Ruff, Flake8, or Black.

---

## Uninstalling Vishwajeet

You can remove the package cleanly at any time using `pip`:

```powershell
python -m pip uninstall vishwajeet-12
```

If you installed the package inside a virtual environment, run `uninstall` using that virtual environment's Python interpreter:

**Windows PowerShell:**

```powershell
.\.venv\Scripts\python.exe -m pip uninstall vishwajeet-12
```

**Linux / macOS:**

```bash
./.venv/bin/python -m pip uninstall vishwajeet-12
```

The package creates no background processes, startup tasks, shell profile edits, or persistent configuration files outside standard `pip` package directories.

---

## Development, Testing, and Building

### Run the Automated Test Suite

```powershell
python -m pytest
```

### Build Source and Wheel Distributions

```powershell
python -m build
```

This creates two artifacts in `dist/`:
- `vishwajeet_12-1.0.0.tar.gz` (source distribution)
- `vishwajeet_12-1.0.0-py3-none-any.whl` (built wheel)

### Test the Built Wheel in a Clean Virtual Environment

```powershell
py -m venv .venv-smoke
.\.venv-smoke\Scripts\python.exe -m pip install dist\vishwajeet_12-1.0.0-py3-none-any.whl
.\.venv-smoke\Scripts\vishwajeet.exe
.\.venv-smoke\Scripts\vishwajeet.exe doctor
```

---

## Publishing to TestPyPI and PyPI

See [PUBLISHING.md](PUBLISHING.md) for a complete, step-by-step walkthrough covering:
1. Local virtual environment setup
2. Running and testing locally
3. Checking package name availability on PyPI
4. Building `sdist` and `wheel` artifacts
5. Validating artifacts with `twine check`
6. Uploading to **TestPyPI** first
7. Uploading to **Production PyPI** after explicit verification

---

## Troubleshooting

- **`vishwajeet: The term 'vishwajeet' is not recognized` (Command Not Found):**
  - Ensure your virtual environment is activated (`.\.venv\Scripts\Activate.ps1` on Windows or `source .venv/bin/activate` on Linux/macOS).
  - If installed globally with `--user`, ensure your Python `Scripts` directory (for example, `%APPDATA%\Python\Python312\Scripts` on Windows or `~/.local/bin` on Linux/macOS) is on your system `PATH`.
  - Alternatively, invoke the CLI directly through the Python interpreter: `python -m vishwajeet`.
- **PowerShell Execution Policy Blocks `Activate.ps1`:**
  - Run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process` in the current PowerShell window, or run commands directly via `.\.venv\Scripts\python.exe` and `.\.venv\Scripts\vishwajeet.exe`.

---

## License

Released under the [MIT License](LICENSE). Copyright (c) 2026 Vishwajeet More.

