# Packaging Audit and Requirements (CYA-WP-0004 T01)

**Date:** 2026-05-27  
**Workplan:** CYA-WP-0004

## Current State Audit

### Packaging Configuration
- **Build system**: `setuptools` (via `pyproject.toml`)
- **Version**: Hardcoded as `0.1.0` in two places:
  - `pyproject.toml`
  - `src/cya/__init__.py`
- **Entry point**: `cya = "cya.cli.main:run"` (correct)
- **Package discovery**: `src` layout via `[tool.setuptools.packages.find]`
- **Dependencies**: Minimal (`typer[standard]`, `rich`)
- **No**:
  - `setuptools_scm` or dynamic versioning
  - `[project.optional-dependencies]`
  - `build` frontend usage
  - `MANIFEST.in` or equivalent include rules
  - `include-package-data` configuration
  - Development/test extras
  - `pyproject.toml` validation for `pip install git+...`

### Current Installation Experience
- Only documented method: `pip install -e .` (editable)
- `pip install git+https://...` is not reliable (version will be wrong, potential missing files)
- No released packages exist yet

### Gaps Identified

**For "Install from Dev Head":**
- No support for clean `pip install "git+https://github.com/worsch/can-you-assist.git@main"`
- Version will be stuck at 0.1.0 even on latest code (bad for debugging)
- Potential missing non-.py files in the sdist/wheel when installing from git
- No documented one-liner or Makefile target for the primary user

**For "Release Packaging":**
- No versioning strategy (how to bump, dev vs release versions)
- No process to build clean, reproducible sdist + wheel
- No `python -m build` usage
- No release checklist or automation (even lightweight)
- No way for others to `pip install can-you-assist` (or a future released name)

**General Technical Debt:**
- Version is duplicated in two places (violates DRY)
- No separation between build-time and runtime concerns
- No packaging tests or verification step

## Requirements for CYA-WP-0004

### Must-Have for Dev-Head Install
1. `pip install "git+https://github.com/worsch/can-you-assist.git"` (and `@main`, `@branch`) must produce a working `cya` with a dev-informative version.
2. The primary user must have a simple, documented way to stay on latest code.
3. Version must clearly indicate it is from development head (e.g., `0.2.0.devN+g<hash>` or similar).

### Must-Have for Release Packaging
1. A clear, repeatable process to cut a new version.
2. Ability to produce clean `sdist` + `wheel` using modern tools (`python -m build`).
3. Version must be single-source-of-truth.
4. Documentation in README + AGENTS.md for both installation methods.

### Nice-to-Have (in scope if low cost)
- Makefile targets for common operations (`make dev-install`, `make dist`, `make check-dist`)
- Basic CI step that verifies packaging works
- Optional dependencies (e.g., `[dev]`, `[test]`)

## Versioning Strategy Recommendation (for T02)

**Recommended approach: Hybrid using `setuptools_scm`**

- For development/git installs: Automatic versions like `0.3.0.dev14+g3f2a1b7.d20260527`
- For releases: Clean versions like `0.3.0`
- Single source of truth in git tags + `pyproject.toml` configuration
- Minimal changes to existing workflow

**Alternative (simpler but less powerful):** Keep static version + manual bumps + release checklist. Only use if `setuptools_scm` is deemed overkill.

**Decision needed in T02.**

## Next Steps

- T02 will decide and implement the versioning approach.
- T03 will focus on making git-based installs reliable.
- T04–T05 will focus on the release side.

This audit serves as the requirements baseline for the rest of the workplan.