path_route_md

# KOMU Command Routing and PATH Behavior

This document explains why `komu` previously worked only inside `.venv`, where the command is created after installation, how PowerShell discovers commands, and what changed in the repository to make the install story more realistic for local users and future GitHub users.

## 1. Why `komu` only worked inside `.venv`

During a development install such as:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
```

Python creates the CLI launcher here:

```text
.\.venv\Scripts\komu.exe
```

When the virtual environment is activated, PowerShell temporarily prepends:

```text
.\.venv\Scripts
```

to PATH for the current shell session.

That is why:

- `komu` works while the venv is active
- `komu` stops being discoverable when the shell is no longer using that venv

This behavior is normal for a development install. It does not mean the CLI entrypoint is broken.

## 2. Where the `komu` command is created after installation

The exact location depends on the installation mode.

### Development venv install

Command location:

```text
<repo>\.venv\Scripts\komu.exe
```

Use case:

- contributors
- local repo development
- tests

### User-level install with `python -m pip install --user .`

Command location:

```text
<USER_BASE>\Scripts\komu.exe
```

You can discover `<USER_BASE>` with:

```powershell
python -c "import site; print(site.USER_BASE)"
```

On Windows, that is typically under the user profile, for example:

```text
%APPDATA%\Python\PythonXY\Scripts
```

### `pipx` install

`pipx` creates an isolated environment for KOMU and then exposes the CLI through the command path managed by `pipx ensurepath`.

This is usually the cleanest end-user install mode for CLI tools.

## 3. How PowerShell discovers commands

PowerShell resolves a command name like `komu` from:

1. aliases
2. functions
3. cmdlets
4. scripts and executables found on PATH

For a Python CLI like KOMU, the important part is the last item:

- `komu.exe` must exist
- the directory containing `komu.exe` must be on PATH

Useful checks:

```powershell
Get-Command komu
where.exe komu
```

If those commands do not find `komu`, PowerShell cannot currently route the command to the installed launcher.

## 4. Which PATH entries matter

The correct PATH entry depends on how KOMU was installed.

### For a venv install

Relevant path:

```text
<repo>\.venv\Scripts
```

This is usually added automatically only when the venv is activated.

### For a user install

Relevant path:

```text
<USER_BASE>\Scripts
```

Discover it with:

```powershell
$userBase = python -c "import site; print(site.USER_BASE)"
Join-Path $userBase "Scripts"
```

### For `pipx`

Relevant path:

- the command path managed by `pipx ensurepath`

After running `python -m pipx ensurepath`, open a new PowerShell window.

## 5. How editable installs behave

Editable install:

```powershell
python -m pip install -e .
```

What it does:

- installs launcher scripts into the current Python environment
- points imports back to the source tree instead of copying package files into `site-packages`

What it does not do:

- it does not make the command globally available outside that environment unless that environment’s Scripts directory is on PATH

So:

- editable install inside `.venv` is venv-local
- editable install with `--user` writes the launcher into the user Scripts directory

## 6. How end users should install the tool

### Recommended for end users

Use `pipx`:

```powershell
python -m pip install --user pipx
python -m pipx ensurepath
pipx install .
```

Once the repo is published:

```powershell
pipx install git+https://github.com/<owner>/<repo>.git
```

Why this is better:

- isolated dependency environment
- clean CLI command exposure
- avoids asking end users to manage a project venv

### Acceptable for single-machine users

Use:

```powershell
python -m pip install --user .
```

Then ensure the user Scripts directory is on PATH.

## 7. Windows troubleshooting for command-not-found

If `komu` is not recognized:

1. run `Get-Command komu`
2. run `where.exe komu`
3. run `python -m pip show komu-cli`
4. confirm how KOMU was installed
5. confirm the matching Scripts directory is on PATH
6. open a new PowerShell session

If `python` is not recognized:

1. run `Get-Command python`
2. run `Get-Command py`
3. check App Execution Aliases in Windows settings
4. ensure the real Python install directory is on PATH

If `Activate.ps1` is blocked:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

## 8. What changed in the repo

The repository now includes explicit packaging and install improvements:

- `pyproject.toml` defines the console script entrypoint:
  - `komu = "komu_cli.cli.app:run"`
- `src/komu_cli/__main__.py` supports:
  - `python -m komu_cli`
- package metadata is more distribution-friendly:
  - classifiers
  - keywords
  - typed-package marker
- `src/komu_cli/py.typed` is included for typed distribution readiness
- packaging tests now verify:
  - script entrypoint
  - package data
  - module entrypoint
- install docs now clearly separate:
  - development venv install
  - user-level install
  - `pipx` / public CLI install

## 9. Practical validation commands

After installation, these commands should be enough to verify routing:

```powershell
python --version
python -m pip --version
python -m pip show komu-cli
Get-Command komu
where.exe komu
komu --help
komu --version
```

If you want to verify the package itself:

```powershell
python -c "import komu_cli; print(komu_cli.__version__)"
python -m komu_cli --help
```

## 10. The real distinction to remember

There are three different command-routing stories:

1. repo venv install
   - command lives in `.venv\Scripts`
   - works when the venv is active

2. user install
   - command lives in the user Scripts directory
   - works when that directory is on PATH

3. `pipx` install
   - command is exposed through `pipx`
   - best choice for end users of a CLI product

KOMU now supports all three properly. The remaining requirement is to choose the correct installation mode for the audience and ensure the matching Scripts path is discoverable by PowerShell.