# dev-publish (Python CLI)

Fast local build+publish utility for Python packages in the `@packages` workspace.

## Installation

The `dev-publish` CLI is included in the `lilith-queue-cli` package:

```bash
cd ~/Code/@packages/queue-py
pip install -e . --break-system-packages
```

## Usage

### Basic Publishing

```bash
# From package directory
cd @ml/content-understanding
dev-publish

# From anywhere
dev-publish /path/to/package
```

### Options

```bash
dev-publish [OPTIONS] [PACKAGE_PATH]

Options:
  -d, --dry-run         Show what would be done without executing
  -s, --skip-build      Skip build step, only publish
  -v, --verbose         Detailed logging output
  --registry TEXT       Override registry URL
  --skip-version-check  Don't check if version already exists
  --help                Show this message and exit
```

### Examples

```bash
# Dry run - see what would happen
dev-publish --dry-run

# Verbose output
dev-publish --verbose

# Skip build (only publish)
dev-publish --skip-build

# Custom registry
dev-publish --registry https://test-pypi.org/

# Combine options
dev-publish --dry-run --verbose
```

## Co-Development Workflow

**Scenario**: Updating `lilith-content-understanding` while working on a consumer app

1. **Make changes to library**:
   ```bash
   cd @ml/content-understanding
   # Edit src/lilith_content_understanding/processor.py
   ```

2. **Fast publish with dev version** (~15 seconds):
   ```bash
   dev-publish
   # Output: Published lilith-content-understanding@0.1.0-dev.1768416890
   ```

3. **Update consumer app**:
   ```bash
   cd ~/Code/@applications/my-app
   pip install lilith-content-understanding==0.1.0-dev.1768416890
   ```

4. **Test changes immediately**

5. **Iterate** (repeat steps 1-4)

6. **When satisfied, publish stable version**:
   ```bash
   cd @ml/content-understanding
   # Update version in pyproject.toml: 0.1.0 → 0.1.1
   git commit -am "feat: add new feature"
   git push  # Forgejo CI publishes stable 0.1.1
   ```

7. **Update consumer to stable**:
   ```bash
   cd ~/Code/@applications/my-app
   pip install --upgrade lilith-content-understanding
   ```

## How It Works

1. **Detects** Python package (checks for pyproject.toml)
2. **Reads** metadata from `[project]` and `[tool.lilith]` sections
3. **Creates** dev version: `{version}-dev.{timestamp}`
4. **Builds** package using `python -m build`
5. **Publishes** to PyPI registry using `twine`

## Dev Version Format

Format: `{base_version}-dev.{timestamp}`

Examples:
- `0.1.0` → `0.1.0-dev.1768416890`
- `1.2.3` → `1.2.3-dev.1768420000`

## Environment Variables

### Required

- `FORGEJO_PYPI_TOKEN` - PyPI registry authentication token

### Optional

- `LOCAL_PUBLISH_PYPI_REGISTRY` - Registry URL
  Default: `http://forge.black.lan/api/packages/lilith/pypi`

## Package Metadata

The CLI reads configuration from `pyproject.toml`:

```toml
[project]
name = "lilith-package-name"
version = "1.0.0"

[tool.lilith]
registry = "forgejo"  # Optional, default: "forgejo"
publish = true        # Optional, default: true
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Invalid arguments |
| 2 | Package detection failed |
| 3 | Metadata validation failed |
| 4 | Build failed |
| 5 | Publish failed |
| 10 | Registry error |

## Troubleshooting

### Error: FORGEJO_PYPI_TOKEN not set

```bash
source ~/.bashrc
# Or set manually:
export FORGEJO_PYPI_TOKEN="your-token-here"
```

### Build Failed

```bash
# Check build system
python -m build --help

# Try with verbose output
dev-publish --verbose
```

### Publish Failed

```bash
# Check twine installation
twine --version

# Check registry connectivity
curl -I http://forge.black.lan/api/packages/lilith/pypi
```

### ModuleNotFoundError

```bash
# Reinstall in editable mode
cd ~/Code/@packages/queue-py
pip install -e . --break-system-packages
```

## Performance

- **Build + Publish**: ~15-20 seconds
- **vs Forgejo CI/CD**: 2-5 minutes
- **Speedup**: 10-15x faster iteration

## API Parity

This Python implementation follows the same protocol as the TypeScript version:
- Identical CLI interface
- Same exit codes
- Same logging format
- Same dev version algorithm

See [PROTOCOL.md](../../../@cli/dev-publish/PROTOCOL.md) for the full specification.

## See Also

- [TypeScript CLI](../../@cli/dev-publish/)
- [PROTOCOL.md](../../@cli/dev-publish/PROTOCOL.md)
- [Workspace Scripts](../../scripts/publishing/)