Metadata-Version: 2.4
Name: mug
Version: 0.1000.5
Summary: Mug CLI and MCP adapter packaged as bundled Rust binaries.
Author: Gritlabs
License-Expression: MIT
Keywords: mug,cli,mcp
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Mug

Mug is distributed on PyPI as a thin Python wrapper around compiled Rust
binaries. The Python package does not implement Mug workflow behavior; it
locates the bundled executables and passes arguments through.

The first real PyPI release target was `0.1000.0`, with Windows as the first
platform proof. Current hotfix releases continue on the `0.1000.x` line.
Native installers may come later, but PyPI is the primary public install path
for this release line.

## Install On A Windows PC

Use a virtual environment for the first smoke test so the installed commands are
easy to remove.

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install mug
```

If you are not using a virtual environment, install with:

```sh
pip install mug
```

## Verify Mug

After install, confirm that the wrapper command is on PATH and that the bundled
Rust binary starts:

```powershell
where mug
mug -v
mug --help
```

The Python package version should be on the current `0.1000.x` release line:

```powershell
python -c "from importlib.metadata import version; print(version('mug'))"
```

`mug -v` should report the same release version as the installed Python
package.

## Repair A Stale Windows Launcher

If a previous install left a broken global launcher earlier on PATH, upgrade or
reinstall Mug from PyPI:

```powershell
python -m pip install --upgrade --force-reinstall mug
```

Then open a new terminal and check:

```powershell
where mug
mug -v
```

The `0.1000.1` and later packages include a compatibility entry point for the legacy
`mug.cli.__main__` launcher shape.

## Verify Mug MCP

`mug-mcp` is the local MCP adapter. In the PyPI package it is installed next to
the bundled `mug` binary and the wrapper supplies the packaged Mug CLI path, so
users do not need to set `MUG_CLI` for the normal package layout.

Confirm the command is installed:

```powershell
where mug-mcp
```

For a quick protocol smoke, send an MCP initialize request followed by a
`mug_health` tool call:

```powershell
@'
{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"pc-smoke","version":"0.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mug_health","arguments":{}}}
'@ | mug-mcp
```

The output should include a `mug_cli` path under the installed Python package,
showing that `mug-mcp` found the bundled Mug CLI without a manual `MUG_CLI`
override.

## Reinstall Or Uninstall During Testing

To reinstall the same version from PyPI:

```powershell
python -m pip install --force-reinstall mug
```

To uninstall:

```sh
python -m pip uninstall mug
```

If you used the virtual environment above, you can also remove the entire
`.venv` directory after deactivating it.

## Deterministic Publish Flow

Mug releases must use the deterministic release entry point instead of ad hoc
natural-language assistant instructions. The normal release path is the
Mug-owned `mug release publish` command. It computes one canonical release
context, queues the checked-in Azure release pipeline only after preflight
passes, monitors the Azure run, and advances Mug's sprint version record only
after public release success is proven.

The active sprint's `sprints.version` stores the latest successfully published
version for that sprint. For a normal patch release, Mug derives the next
candidate from that value. Do not manually edit PyPI source version files,
manually advance `sprints.version` before publishing, manually queue Azure from
the UI, manually upload wheels, or manually push release tags.

Review the next patch release before publishing:

```sh
mug release publish --next-patch --dry-run --json
```

The dry-run prints the latest published version, candidate release version,
sprint source, current git commit, deterministic tag such as `mug-v0.1000.3`,
PyPI target, Azure template parameters, and side-effect policy. It must report
that Azure queueing, PyPI upload, git tag creation, git tag push,
`sprints.version` update, and release receipt writing are skipped.

Publish the reviewed next patch explicitly:

```sh
mug release publish --next-patch --confirm --json
```

When you need an explicit version confirmation, use the matching `--version`
form instead:

```sh
mug release publish --version 0.1000.3 --dry-run --json
mug release publish --version 0.1000.3 --confirm --json
```

The explicit version must match the release context. If it does not, the
command fails before Azure can be queued.

Confirmed publish refuses to continue when preflight cannot prove a safe
release context. Examples include malformed version state, an existing PyPI
version, an existing or mismatched release tag, release-relevant dirty tracked
files, failed local/pipeline projection checks, or any mismatch between the
selected release context and the public artifact projections.

Azure owns the release side effects after Mug queues the approved run. The
Azure pipeline builds the Windows wheel, smoke-checks the installed package,
uploads to PyPI, creates the deterministic release tag, pushes the remote tag,
and emits release evidence. The local Mug command is the controller and monitor;
it does not build a local wheel, upload to PyPI from the local machine, create
the tag locally, or push the tag itself.

After Azure success and public verification, Mug advances the current sprint's
`sprints.version` to the successfully published version. That field is a record
of release success, not a manual pre-publish input for normal one-command
publishing.

If the local publish controller is interrupted after Azure may have completed,
reconcile from public projections instead of rerunning a publish:

```sh
mug release reconcile --version 0.1000.3 --json
```

Reconcile inspects the PyPI version URL, deterministic git tag ref, tag target,
and any receipt or projection source available. It advances `sprints.version`
only when those public projections prove the release succeeded. It refuses when
the PyPI version is missing, the deterministic tag is missing, or the tag target
is wrong when commit verification is available. Reconcile does not upload to
PyPI, create tags, push tags, or queue Azure.

`mug release prepare --version <version> --json` and
`python tools/pypi/release.py` are not the normal publish path. Treat them as
legacy, diagnostic, or repair-only surfaces unless a future approved
deliverable explicitly restores them to the release ceremony.

## Packaging Boundary

The Python wrapper is only a delivery layer. Product workflow state, validation,
governing rules, Journal behavior, and MCP behavior live in the Rust binaries.
