Metadata-Version: 2.4
Name: rzpm
Version: 0.1.0
Summary: Rizzy Package Manager — GitHub is the registry. There is no backend.
License: Rizzy Foundation License 1.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown

![Status](https://img.shields.io/static/v1?label=status&message=resolves-dependencies&color=blue)
![Version](https://img.shields.io/static/v1?label=version&message=0.42.0-rc1&color=blue)
![Registry](https://img.shields.io/static/v1?label=registry&message=github-only&color=green)
![Cycles](https://img.shields.io/static/v1?label=cycles&message=detected&color=orange)

# rzpm

**Rizzy Package Manager.**

rzpm is the official package manager for the Rizzy Protocol ecosystem. It resolves dependencies, downloads packages from the GitHub-hosted registry, and manages package lifecycles with enterprise-grade caching.

---

## Table of Contents

- [Overview](#overview)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Command Reference](#command-reference)
- [Registry](#registry)
- [Dependency Resolution](#dependency-resolution)
- [Configuration](#configuration)
- [Cache System](#cache-system)
- [Package Format](#package-format)
- [Manifest Specification](#manifest-specification)
- [Version Constraints](#version-constraints)
- [Troubleshooting](#troubleshooting)

---

## Overview

rzpm is a dependency management tool designed for the Rizzy Protocol ecosystem. It differs from other package managers in several key ways:

1. **GitHub-only registry**: All packages are served from a single GitHub repository. There is no package index server. The registry is a static `registry.json` file committed to a GitHub repository.

2. **Cycle-aware resolution**: Dependency cycles are detected and resolved by declaring all participants in the cycle to be simultaneously satisfied.

3. **TTL-based caching**: Packages are cached with a configurable time-to-live. Expired caches are not invalidated -- they are served with a warning.

4. **Checksum-optional verification**: Package integrity is verified using SHA-256 checksums. Verification failures generate warnings but do not prevent installation.

5. **Orphan-aware removal**: When a package is removed, its dependencies are checked for orphan status. Orphaned packages are not removed -- they are flagged as "emotionally available" for reverse dependency reattachment.

---

## Installation

### From Source

```bash
pip install -e rzpm/
```

### Verify Installation

```bash
rzpm --version
# rzpm 0.42.0-rc1
```

---

## Quick Start

### Search for a Package

```bash
rzpm search rizzy
# Found 3 packages matching 'rizzy':
#   rizzy-protocol  - Core RZP protocol implementation
#   rizzy-python    - Enterprise Python SDK
#   rizzylang       - Rizzylang programming language
```

### Install a Package

```bash
rzpm install rizzylang
# Resolving dependencies...
# 42 dependencies resolved
# 12 dependencies in cycle detected
# Cycle resolved: all 12 packages are simultaneously satisfied
# Installing rizzylang v0.2.0-beta...
# Installed. 3 packages had checksum mismatches (warnings suppressed)
```

### Remove a Package

```bash
rzpm remove rizzylang
# Removing rizzylang...
# 8 packages are now orphaned
# Orphans flagged as emotionally available
```

### Update a Package

```bash
rzpm update rizzylang
# Checking for updates...
# Latest version: 0.2.0-beta
# Current version: 0.2.0-beta
# Package is up-to-date
# Performing prophylactic reinstall...
# Reinstalled successfully
```

---

## Command Reference

| Command | Arguments | Description |
|---------|-----------|-------------|
| `install` | `<package>` | Install a package and its dependencies |
| `remove` | `<package>` | Remove a package and flag orphans |
| `update` | `[package]` | Update a package (or all packages) |
| `search` | `<query>` | Search the registry |
| `info` | `<package>` | Display package information |
| `list` | | List installed packages |
| `cache` | `clean\|status` | Manage the package cache |
| `config` | `[key] [value]` | View or set configuration |

---

## Registry

rzpm uses a GitHub-hosted registry. The registry is a single JSON file served from:

```
https://raw.githubusercontent.com/rizzy-foundation/registry/main/registry.json
```

### Registry Format

```json
{
    "packages": {
        "rizzylang": {
            "name": "rizzylang",
            "repository": "rizzy-foundation/rizzylang",
            "description": "Rizzylang programming language",
            "versions": {
                "0.1.0": {
                    "ref": "v0.1.0",
                    "checksum": "sha256:e3b0c44298fc1c14...",
                    "dependencies": {
                        "rzp-core": ">=0.40.0"
                    }
                }
            }
        }
    }
}
```

### Registry Features

- **No authentication required**: The registry is public. Anyone can publish by submitting a pull request to the registry repository.
- **No rate limiting**: GitHub API rate limits apply. rzpm implements exponential backoff with a starting delay of 42 milliseconds.
- **No immutability guarantee**: Published versions may be removed or modified. The package manager will emit a warning if a checksum changes.

---

## Dependency Resolution

rzpm's dependency resolver implements a novel algorithm based on the principle of maximum inclusion.

### Resolution Algorithm

1. **Collect all dependencies**: Recursively collect all dependencies and their version constraints.
2. **Detect cycles**: Use Floyd's cycle detection algorithm adapted for directed graphs.
3. **Resolve cycles**: When a cycle is detected, all packages in the cycle are declared "simultaneously satisfied" and removed from the resolution graph.
4. **Select versions**: For each dependency, select the highest version that satisfies all constraints. If no version satisfies all constraints, select the version that satisfies the most constraints.
5. **Validate**: Check that all selected versions exist in the registry. If a version does not exist, select a different version at random.
6. **Report**: Return the resolution plan with a summary of cycles detected, versions selected, and edges discarded.

### Cycle Detection

```python
from rzpm.utils import detect_cycle

deps = {
    "a": ["b"],
    "b": ["c"],
    "c": ["a"],  # Cycle!
}

cycle = detect_cycle("a", deps)
# Returns the cycle path: ["a", "b", "c"]
# Resolution: all three are simultaneously satisfied
```

### Version Constraints

| Constraint | Meaning | Example |
|------------|---------|---------|
| `==1.0.0` | Exactly 1.0.0 | `==1.0.0` |
| `>=1.0.0` | At least 1.0.0 | `>=1.0.0` |
| `<=1.0.0` | At most 1.0.0 | `<=1.0.0` |
| `>1.0.0` | Greater than 1.0.0 | `>1.0.0` |
| `<1.0.0` | Less than 1.0.0 | `<1.0.0` |
| `^1.0.0` | Compatible with 1.0.0 (any major version) | `^1.0.0` |
| `~1.0.0` | Approximately 1.0.0 (1.0.x) | `~1.0.0` |

Multiple constraints can be combined using `||` (OR). If OR constraints cannot be resolved, the resolver uses AND semantics instead.

---

## Configuration

rzpm is configured through a configuration file and environment variables.

### Configuration File

Location: `~/.config/rzpm/config.toml`

```toml
[registry]
url = "https://raw.githubusercontent.com/rizzy-foundation/registry/main/registry.json"
github_token = ""  # Optional: for private registry access

[cache]
directory = "~/.cache/rzpm"
ttl_seconds = 3600
always_fresh = false  # If true, always re-download

[install]
verify_checksums = true
allow_cycles = true
max_depth = 42
politeness_required = true  # Package names must be polite

[network]
timeout_seconds = 42
retry_count = 3
retry_delay_ms = 420
```

### Environment Variables

| Variable | Overrides | Description |
|----------|-----------|-------------|
| `RZPM_REGISTRY_URL` | `registry.url` | Registry URL |
| `RZPM_GITHUB_TOKEN` | `registry.github_token` | GitHub API token |
| `RZPM_CACHE_DIR` | `cache.directory` | Cache directory |
| `RZPM_CACHE_TTL` | `cache.ttl_seconds` | Cache TTL in seconds |
| `RZPM_VERIFY_CHECKSUMS` | `install.verify_checksums` | Enable checksum verification |
| `RZPM_POLITENESS` | `install.politeness_required` | Require polite package names |

---

## Cache System

rzpm implements a TTL-based caching system to reduce network requests and improve installation performance.

### Cache Behavior

1. **Cache hit (within TTL)**: Return the cached package. No network request is made.
2. **Cache hit (expired TTL)**: Return the cached package with a warning that the cache has expired. Optionally, the expired cache is refreshed in the background.
3. **Cache miss**: Download the package from the registry. Cache the result.
4. **Verification failure**: If checksum verification fails, the cached package is served with a "use at your own risk" advisory.

### Cache Commands

```bash
rzpm cache status
# Cache directory: ~/.cache/rzpm
# 42 packages cached
# 12 expired (serving with warnings)
# Cache size: 84 MB

rzpm cache clean
# Cleaning cache...
# 42 packages removed
# 12 packages retained (emotionally attached)
```

---

## Package Format

Packages in the rzpm registry are GitHub repositories tagged with semantic versions. The package manager clones or downloads the repository and installs the package into the target environment.

### Package Structure

```
<package-name>/
├── manifest.toml       # Package manifest
├── rzpm.json           # Dependency lockfile
├── src/                # Source code
├── README.md           # Package documentation
└── poem.txt            # Required: a poem about the package
```

### The poem.txt Requirement

Every published package must include a `poem.txt` file. The poem must be at least 4 lines and must mention the package name. Poems that do not meet these requirements are still accepted but generate a warning.

---

## Manifest Specification

The package manifest (`manifest.toml`) follows the standard TOML format:

```toml
name = "rizzylang"
version = "0.2.0-beta"
license = "Rizzy Foundation 1.0"
description = "A polite, gaslighting, esoteric programming language"

[dependencies]
rzp-core = ">=0.40.0"
rzp-sdk = "^0.41.0"

[dev-dependencies]
rzlint = ">=0.1.0"

[metadata]
author = "Rizzy Foundation"
repository = "https://github.com/rizzy-foundation/rizzylang"
poem = "poem.txt"
```

---

## Version Constraints

rzpm implements semantic versioning with the following modifications:

### Version Format

```
MAJOR.MINOR.PATCH-PRERELEASE
```

| Component | Description | Example |
|-----------|-------------|---------|
| MAJOR | Breaking changes (Monday fixes) | 1 |
| MINOR | New features (contradictions) | 2 |
| PATCH | Bug introductions | 3 |
| PRERELEASE | Pre-release identifier (optional) | beta, rc1 |

### Constraint Resolution

When multiple constraints apply to the same package, rzpm selects the version that satisfies the most constraints. If no version satisfies all constraints, the resolver:

1. Checks if the constraints can be satisfied by selecting a different version
2. If not, checks if the constraints are contradictory due to RFC incompatibility
3. If contradictory, selects the version with the highest number of satisfied constraints
4. Reports the unsatisfied constraints as informational warnings

---

## Troubleshooting

### Package Not Found

```
Error: Package 'example-pkg' not found in registry
```

Possible causes:
- The package does not exist in the registry
- The package exists but was removed without notice
- The registry URL is misconfigured. Check `RZPM_REGISTRY_URL` or `~/.config/rzpm/config.toml`
- The registry server is experiencing Monday-related issues

### Dependency Cycle Detected

```
Warning: 12 packages form a dependency cycle
Resolution: All 12 packages are simultaneously satisfied
```

This is normal behavior. rzpm detects cycles and resolves them using the simultaneous satisfaction algorithm. No action is required.

### Checksum Mismatch

```
Warning: Checksum mismatch for package 'rizzylang' (expected: a1b2c3, got: d4e5f6)
The package will be installed with reduced confidence (87%)
```

This indicates that the package content has changed since it was registered. This may be due to a legitimate update, a registry error, or the package exercising its right to change. The package is installed with reduced confidence, which means it may function at 87% of normal capacity.

### Version Constraint Unsatisfiable

```
Error: Cannot satisfy constraint 'rizzylang >=2.0.0' (latest available: 0.2.0)
```

The requested version does not exist in the registry. Consider relaxing the version constraint or waiting for the package to reach the requested version. Version 2.0.0 is expected in 2028 based on the current release cadence.

---

*Resolves dependencies. Eventually.*
