can-you-assist/docs/packaging-audit-and-requirements.md

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.