Metadata-Version: 2.4
Name: unvibecode
Version: 0.3.4
Summary: Turn complex code into connected LLM context, business workflows, and critical risk findings
Author: UnvibeCode
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: jsonschema>=4.20
Requires-Dist: openai<3,>=2.50
Requires-Dist: pyvis>=0.3.2
Requires-Dist: PyYAML>=6.0
Requires-Dist: tiktoken>=0.8
Requires-Dist: tinycss2>=1.2
Requires-Dist: tree-sitter-language-pack>=0.9
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"

# UnvibeCode — Private Production Source & Operations

This private repository is the **single source of truth for UnvibeCode**.

A fresh clone of this repository must always be sufficient to:

1. modify UnvibeCode,
2. run tests,
3. build the Python package,
4. validate the customer workflow,
5. publish a new PyPI release.

Do **not** depend on old OneDrive folders, ZIP backups, extracted wheels, `site-packages`, or historical `dist` directories.

---

## 1. Current Architecture

```text
CUSTOMER MACHINE
│
├── Python package: unvibecode
├── Repository parsing
├── Code graph construction
├── Context generation
├── Business workflow analysis
├── Risk-analysis orchestration
├── Report generation
│
└──────── HTTPS ────────► HOSTED GATEWAY
                           │
                           ├── Provider credentials
                           ├── Model access
                           ├── Request controls
                           ├── Usage controls
                           └── Spend protection
```

The customer's repository is processed primarily on the customer's machine. Model requests required by the analysis workflow are routed through the hosted UnvibeCode gateway.

---

## 2. Hosted Production Gateway

Production API:

```text
https://shipready-api.alphashots.ai/v1/responses
```

Health endpoint:

```text
https://shipready-api.alphashots.ai/health
```

Production flow:

```text
Internet
   ↓
Nginx / HTTPS
   ↓
Uvicorn
   ↓
UnvibeCode API Gateway
   ↓
Model Provider
```

Production gateway directory:

```text
/home/yash/shipready_api_gateway_v1
```

Nginx site configuration:

```text
/etc/nginx/sites-available/shipready-api
```

Runtime environment and provider credentials:

```text
/etc/shipready/shipready-api.env
```

The gateway is responsible for provider credentials, model access, request validation, payload protection, concurrency controls, usage metering, spend protection, and emergency service controls.

### Secrets

Never commit:

```text
.env
.env.*
API keys
provider credentials
private keys
GitHub tokens
PyPI tokens
server secrets
```

No production credential should be required inside the Python package.

Minimum server health checks:

```bash
sudo nginx -t
sudo systemctl reload nginx
curl -i http://127.0.0.1:8100/internal/health
curl -i https://shipready-api.alphashots.ai/health
```

---

## 3. Repository Structure

```text
unvibecode-product-private/
│
├── README.md
├── pyproject.toml
├── .gitignore
├── .gitattributes
│
├── src/
│   ├── unvibecode/
│   │   ├── __init__.py
│   │   └── __main__.py
│   │
│   └── shipreadyv2/
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py
│       ├── customer_runner.py
│       ├── SOURCE_MANIFEST.json
│       └── engine_sources/
│           ├── 00a_shipreadyv2_fast_lane_v11_api_context_bundle.py
│           ├── 01_shipreadyv2_merged_graph_pipeline_5chunks.py
│           ├── 02_shipreadyv2_prepare_pass1_inputs.py
│           ├── 03_shipreadyv2_pass1_full_runner.py
│           ├── 04_shipreadyv2_business_path_compiler.py
│           ├── 05_shipreadyv2_critical_business_insight_selector_v4.py
│           ├── 06_shipreadyv2_step4_v2_with_v4_inputs.py
│           ├── agent_knowledge_graph.db
│           ├── archetype_taxonomy.yaml
│           ├── archetype_taxonomy_pass1_compact.yaml
│           ├── build_pass1_compact_taxonomy.py
│           ├── generate_combinedjson.py
│           ├── normalized_business_path.schema.json
│           ├── shipready_business_insight_implementation_plan_v2.md
│           └── universal_insight_rules.yaml
│
└── tests/
```

---

## 4. Source Ownership

### `src/unvibecode`

Public package compatibility layer for:

```powershell
python -m unvibecode
```

### `src/shipreadyv2/cli.py`

Handles CLI behavior, command arguments, gateway configuration, and starting repository reviews.

### `src/shipreadyv2/customer_runner.py`

Handles repository-size routing, pipeline orchestration, progress reporting, execution of analysis stages, customer result generation, and browser/report behavior.

### `src/shipreadyv2/engine_sources`

This directory contains the **core UnvibeCode analysis engine**. Treat everything inside this directory as proprietary production source.

Main pipeline:

```text
00a → Connected Code Map / repository context

01 → 02 → 03 → 04 → 05 → 06
                    ↓
          Business Workflow & Risk Review
```

Supporting taxonomies, schemas, rules, and knowledge files used by the engine also live here.

---

## 5. Files That Are NOT Source

Never treat these as authoritative:

```text
.venv/
build/
dist/
*.egg-info/
__pycache__/
.pytest_cache/
shipready_results/
```

Also never edit:

```text
site-packages/
```

Generated wheels and `.tar.gz` files are outputs, not source.

---

## 6. GitHub Is the Source of Truth

Private repository:

```text
https://github.com/FinanceFlash/unvibecode-product-private
```

Operating model:

```text
Private GitHub
      ↓
git clone
      ↓
Temporary local working copy
      ↓
modify source
      ↓
tests + build + validation
      ↓
git commit + push
      ↓
Private GitHub
      ↓
tagged release
      ↓
PyPI
```

GitHub is permanent. Local working copies are disposable.

A developer must be able to delete the local repository completely, clone GitHub again, and reproduce the production package. If that is not possible, something required for production is missing from GitHub.

---

## 7. Start Work on Any Computer

Clone:

```powershell
git clone https://github.com/FinanceFlash/unvibecode-product-private.git "D:\unvibecode"
```

Enter the repository:

```powershell
Set-Location "D:\unvibecode"
```

Create a clean environment:

```powershell
py -3.13 -m venv ".venv"
```

Install development tools:

```powershell
& ".\.venv\Scripts\python.exe" -m pip install --upgrade pip build pytest twine
```

Build:

```powershell
& ".\.venv\Scripts\python.exe" -m build .
```

Install the generated wheel:

```powershell
$wheel=(Get-ChildItem ".\dist\*.whl" | Sort-Object LastWriteTime -Descending | Select-Object -First 1); & ".\.venv\Scripts\python.exe" -m pip install --force-reinstall $wheel.FullName
```

Run tests:

```powershell
& ".\.venv\Scripts\python.exe" -m pytest -q
```

Validated `0.3.3` baseline:

```text
11 tests passing
```

---

## 8. Change a `.py` File

Always edit the canonical source in this repository.

Never modify copies inside `site-packages`, `build`, `dist`, old project folders, or old ZIP files.

Example:

```text
src\shipreadyv2\engine_sources\05_shipreadyv2_critical_business_insight_selector_v4.py
```

Syntax-check the changed Python file:

```powershell
& ".\.venv\Scripts\python.exe" -m py_compile ".\src\shipreadyv2\engine_sources\05_shipreadyv2_critical_business_insight_selector_v4.py"
```

Run all tests:

```powershell
& ".\.venv\Scripts\python.exe" -m pytest -q
```

Do not continue with a release if tests fail.

---

## 9. `SOURCE_MANIFEST.json`

Authoritative engine hashes are stored in:

```text
src\shipreadyv2\SOURCE_MANIFEST.json
```

When a listed engine file changes:

1. calculate its new LF-normalized SHA-256,
2. update only that file's stored hash,
3. add a short description to `engine_changes_from_baseline`,
4. leave unrelated hashes unchanged.

Example:

```powershell
$relative="engine_sources/01_shipreadyv2_merged_graph_pipeline_5chunks.py"; & ".\.venv\Scripts\python.exe" -c "from pathlib import Path; import hashlib; p=Path('src/shipreadyv2')/'$relative'; print(hashlib.sha256(p.read_bytes().replace(bytes([13,10]),bytes([10]))).hexdigest())"
```

Do not add ordinary tests, README files, or packaging files to the engine manifest.

---

## 10. Versioning

A PyPI release cannot replace an already published version.

For a normal compatible change:

```text
0.3.3 → 0.3.4
```

Update the version in:

```text
pyproject.toml
src\shipreadyv2\__init__.py
src\shipreadyv2\SOURCE_MANIFEST.json
tests\test_package.py
```

Use a patch version for fixes/tuning, a minor version for significant new functionality, and a major version for breaking changes.

---

## 11. Review the Exact Change

```powershell
git status --short
```

```powershell
git --no-pager diff
```

Confirm that no wheel, virtual environment, generated result, secret, API key, token, or `.env` file is included.

---

## 12. Build a Production Candidate

Remove old build outputs:

```powershell
Remove-Item -Recurse -Force ".\dist" -ErrorAction SilentlyContinue
```

```powershell
Remove-Item -Recurse -Force ".\build" -ErrorAction SilentlyContinue
```

```powershell
Get-ChildItem -Recurse -Directory -Filter "*.egg-info" | Remove-Item -Recurse -Force
```

Run tests:

```powershell
& ".\.venv\Scripts\python.exe" -m pytest -q
```

Build:

```powershell
& ".\.venv\Scripts\python.exe" -m build .
```

Validate distributions:

```powershell
& ".\.venv\Scripts\python.exe" -m twine check ".\dist\*"
```

Expected:

```text
dist/
├── unvibecode-<VERSION>-py3-none-any.whl
└── unvibecode-<VERSION>.tar.gz
```

---

## 13. Validate the Actual Wheel

Do not validate only from the editable source tree.

Create a clean external environment:

```powershell
py -3.13 -m venv "D:\unvibecode_release_validation"
```

Install/upgrade pip:

```powershell
& "D:\unvibecode_release_validation\Scripts\python.exe" -m pip install --upgrade pip
```

Install the newly built wheel:

```powershell
$wheel=(Get-ChildItem ".\dist\*.whl" | Sort-Object LastWriteTime -Descending | Select-Object -First 1); & "D:\unvibecode_release_validation\Scripts\python.exe" -m pip install --force-reinstall $wheel.FullName
```

Verify version:

```powershell
& "D:\unvibecode_release_validation\Scripts\python.exe" -m unvibecode --version
```

Verify help:

```powershell
& "D:\unvibecode_release_validation\Scripts\python.exe" -m unvibecode --help
```

Run a real repository review:

```powershell
& "D:\unvibecode_release_validation\Scripts\python.exe" -m unvibecode review --repository "D:\upstox"
```

A successful normal repository review should create:

```text
01_connected_code_map_for_llm.html
complete_repository_context_for_llm.zip
02_business_workflow_map.html
03_business_risk_findings.html
```

Only continue when the actual wheel passes the real customer workflow.

---

## 14. Save the Change Permanently

```powershell
git status --short
```

```powershell
git --no-pager diff
```

```powershell
git add .
```

```powershell
git commit -m "Describe the production change"
```

```powershell
git push origin main
```

Once pushed, GitHub—not the local computer—is the permanent record.

---

## 15. Tag a Validated Release

```powershell
git tag -a "v<VERSION>" -m "Validated UnvibeCode <VERSION>"
```

```powershell
git push origin "v<VERSION>"
```

Example:

```text
v0.3.4
```

Tags make it possible to reconstruct exactly which source produced each PyPI release.

---

## 16. Publish to PyPI

Only publish after:

```text
syntax check
      ↓
tests
      ↓
build
      ↓
twine check
      ↓
fresh-environment installation
      ↓
real customer workflow
```

Upload only the new release artifacts:

```powershell
& ".\.venv\Scripts\python.exe" -m twine upload ".\dist\unvibecode-<VERSION>-py3-none-any.whl" ".\dist\unvibecode-<VERSION>.tar.gz"
```

Never upload an old `dist` directory wholesale.

After publishing, create another clean environment:

```powershell
py -3.13 -m venv "D:\unvibecode_public_validation"
```

Install the exact PyPI version:

```powershell
& "D:\unvibecode_public_validation\Scripts\python.exe" -m pip install --no-cache-dir "unvibecode==<VERSION>"
```

Verify:

```powershell
& "D:\unvibecode_public_validation\Scripts\python.exe" -m unvibecode --version
```

Run the real customer workflow again:

```powershell
& "D:\unvibecode_public_validation\Scripts\python.exe" -m unvibecode review --repository "D:\upstox"
```

A release is complete only after the **PyPI-installed package** works.

---

## 17. Customer Usage

Install:

```powershell
pip install unvibecode
```

Review a repository:

```powershell
python -m unvibecode review --repository "D:\your_repository"
```

Results are written automatically under:

```text
shipready_results/
```

A normal repository produces:

```text
Connected Code Map
Complete Repository Context
Business Workflow Map
Business Risk Findings
```

---

## 18. Sustainable Operating Rule

For any future `.py` change:

```text
1. Clone/pull private GitHub
2. Edit canonical source
3. Syntax-check changed Python
4. Update SOURCE_MANIFEST if required
5. Update/add tests
6. Run all tests
7. Increment version if releasing
8. Build wheel + tar.gz
9. Run twine check
10. Install wheel in clean environment
11. Run real repository review
12. Review git diff
13. Commit
14. Push to private GitHub
15. Tag validated release
16. Publish to PyPI
17. Install from PyPI and test again
```

The private GitHub repository must always contain everything required to rebuild UnvibeCode from source, except production credentials and other server-only secrets.

---

## 19. Never Do These

Do not:

- modify installed `site-packages`,
- modify files inside `dist`,
- use old ZIPs as source,
- use old OneDrive project copies as source,
- keep production-only changes on one laptop,
- commit `.env` files,
- commit provider credentials,
- commit PyPI tokens,
- commit GitHub authentication tokens,
- release without testing the built wheel,
- overwrite an existing PyPI version,
- make engine changes without updating the manifest when required.

---

## Production Principle

```text
GitHub = source
PyPI = distribution
Customer machine = local execution
Hosted gateway = model access and service controls
Server secrets = server only
```

The private GitHub repository is the authoritative production source for UnvibeCode.
