nexus-claude-api/docs/PACKAGING_DISTRIBUTION.md

# Python Internal Distribution Guide

This document describes how to distribute `nexus-claude-api` internally without publishing to PyPI.

## Recommended Options

Use one of these two approaches:

- **Wheel distribution**: build a `.whl` file and send it to colleagues. This is best for stable internal releases.
- **Private Git installation**: let colleagues install directly from the company Git repository. This is best for teammates who can access the source code or need frequent updates.

Both options require:

- Python `>=3.11`
- Access to PyPI or the company Python package mirror for runtime dependencies
- A personal AI Nexus API key

Do not share `nexus-claude-api.local.json`, `.env`, logs, or any personal API key.

## Option 1: Build and Share a Wheel

A wheel is the standard Python install package format. It is not an `.exe`; colleagues install it with `pip`, then run the installed `nexus-claude-api` command.

### Publisher Steps

1. Confirm the package version in `pyproject.toml`:

   ```toml
   [project]
   name = "nexus-claude-api"
   version = "0.1.0"
   ```

   Update the version for every released package. Avoid sending different builds with the same version.

2. Run the supported checks:

   ```powershell
   uv sync --extra dev
   uv run pytest
   uv run nexus-claude-api start --dry-run
   ```

3. Build the package:

   ```powershell
   uv build
   ```

   This creates files under `dist/`, usually:

   ```text
   dist/nexus_claude_api-0.1.0-py3-none-any.whl
   dist/nexus_claude_api-0.1.0.tar.gz
   ```

4. Test the wheel in a clean environment:

   ```powershell
   py -3.11 -m venv C:\Temp\nexus-claude-api-test
   C:\Temp\nexus-claude-api-test\Scripts\python.exe -m pip install .\dist\nexus_claude_api-0.1.0-py3-none-any.whl
   C:\Temp\nexus-claude-api-test\Scripts\nexus-claude-api.exe start --dry-run
   ```

5. Send only the `.whl` file to colleagues through an approved internal channel.

### Colleague Installation

Install the wheel:

```powershell
py -3.11 -m pip install .\nexus_claude_api-0.1.0-py3-none-any.whl
```

Configure the personal Nexus key:

```powershell
nexus-claude-api config set --api-key "your-nexus-api-key"
```

Start the local proxy and print the Claude Code helper:

```powershell
nexus-claude-api start --port 4141 --claude-code
```

If PowerShell cannot find the installed script, use the module form:

```powershell
py -3.11 -m nexus_claude_api start --port 4141 --claude-code
```

### Upgrade

Send a new wheel with a new version, then ask colleagues to run:

```powershell
py -3.11 -m pip install --upgrade .\nexus_claude_api-0.1.1-py3-none-any.whl
```

## Option 2: Install from Private Git

Private Git installation avoids manual wheel sharing. It still uses the Python package metadata from `pyproject.toml`, so the installed command is the same.

### Publisher Steps

1. Push the code to the company Git repository.

2. Update the version in `pyproject.toml` for each released version.

3. Tag stable versions:

   ```powershell
   git tag v0.1.0
   git push origin v0.1.0
   ```

   For the next release:

   ```powershell
   git tag v0.1.1
   git push origin v0.1.1
   ```

4. Share an install command that points to a tag:

   ```powershell
   py -3.11 -m pip install "git+https://company-git.example.com/group/nexus-claude-api.git@v0.1.0"
   ```

Prefer tags or exact commit SHAs. Avoid asking normal users to install from `main`, because repeated installs can produce different code over time.

### Colleague Installation

Install from the company Git repository:

```powershell
py -3.11 -m pip install "git+https://company-git.example.com/group/nexus-claude-api.git@v0.1.0"
```

Configure the personal Nexus key:

```powershell
nexus-claude-api config set --api-key "your-nexus-api-key"
```

Start the local proxy:

```powershell
nexus-claude-api start --port 4141 --claude-code
```

### Upgrade

Upgrade to a newer tag:

```powershell
py -3.11 -m pip install --upgrade "git+https://company-git.example.com/group/nexus-claude-api.git@v0.1.1"
```

### Development Clone

For colleagues who will modify or test the source code:

```powershell
git clone https://company-git.example.com/group/nexus-claude-api.git
cd nexus-claude-api
uv sync --extra dev
uv run nexus-claude-api start --dry-run
```

## Choosing Between the Two

- Use **wheel distribution** for normal internal users who only need a stable tool.
- Use **private Git installation** for colleagues who understand the repository, need fast updates, or help develop the project.
- Keep version numbers and Git tags aligned. For example, `pyproject.toml` version `0.1.0` should correspond to tag `v0.1.0`.

## Release Checklist

Before sharing a release:

- Run `uv run pytest`.
- Run `uv run nexus-claude-api start --dry-run`.
- Test wheel installation in a clean Python environment.
- If using Git installation, test install from the exact tag.
- Confirm no personal credentials are included.
- Confirm `nexus-claude-api.local.json`, `.env`, logs, caches, and `dist/` artifacts are not committed accidentally.