diff --git a/.gitea/workflows/publish-python-package.yml b/.gitea/workflows/publish-python-package.yml new file mode 100644 index 0000000..f0cfbcd --- /dev/null +++ b/.gitea/workflows/publish-python-package.yml @@ -0,0 +1,37 @@ +name: Publish Python package + +on: + push: + tags: + - "v*" + workflow_dispatch: + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - name: Check out source + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install packaging tools + run: python -m pip install --upgrade build twine + + - name: Build distributions + run: python -m build + + - name: Validate distributions + run: python -m twine check dist/* + + - name: Upload to Gitea PyPI + env: + TWINE_USERNAME: ${{ secrets.GITEA_PACKAGE_USER }} + TWINE_PASSWORD: ${{ secrets.GITEA_PACKAGE_TOKEN }} + run: >- + python -m twine upload + --repository-url https://gitea.coulomb.social/api/packages/coulomb/pypi + dist/* diff --git a/Makefile b/Makefile index ff2ccc3..e67b5ef 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,14 @@ # Makefile for Kaizen Agentic development tasks -.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev install-local install-global standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-install-cli release-check release-prepare release-test release-publish release-finalize release-rollback +.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev install-local install-global standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-install-cli release-check release-prepare release-test release-publish publish-gitea package-check release-finalize release-rollback # Variables VENV = .venv VENV_PYTHON = $(VENV)/bin/python VENV_PIP = $(VENV)/bin/pip +GITEA_PACKAGE_OWNER ?= coulomb +GITEA_PYPI_REPOSITORY_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi +GITEA_PYPI_SIMPLE_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi/simple/ # Default target help: @@ -43,8 +46,10 @@ help: @echo "Release Management:" @echo " release-check - Validate release readiness (tests, linting, version consistency)" @echo " release-prepare - Prepare release (update versions, build packages)" + @echo " package-check - Build and validate wheel/sdist with twine" + @echo " publish-gitea - Publish dist/* to Coulomb Gitea PyPI registry" @echo " release-test - Test publication workflow using TestPyPI" - @echo " release-publish - Publish to production PyPI" + @echo " release-publish - Publish to production PyPI (pypi.org)" @echo " release-finalize - Post-release tasks (tags, GitHub release, documentation)" @echo " release-rollback - Emergency rollback procedures" @echo "" @@ -915,8 +920,24 @@ release-prepare: release-check clean ls -la dist/ | grep "$$VERSION" || echo " • Package files:"; ls -la dist/; \ echo ""; \ echo "💡 Next steps:"; \ - echo " • Run 'make release-test' to test publication"; \ - echo " • Run 'make release-publish' for production release" + echo " • Run 'make publish-gitea' for Coulomb Gitea PyPI"; \ + echo " • Run 'make release-test' to test publication on TestPyPI"; \ + echo " • Run 'make release-publish' for pypi.org (when configured)" + +# Build and validate distributions +package-check: release-prepare + $(VENV_PYTHON) -c "import twine" 2>/dev/null || $(VENV_PIP) install twine + $(VENV_PYTHON) -m twine check dist/* + +# Publish to Coulomb Gitea PyPI registry +publish-gitea: package-check +ifndef TWINE_USERNAME + $(error TWINE_USERNAME is required (e.g. export TWINE_USERNAME=)) +endif +ifndef TWINE_PASSWORD + $(error TWINE_PASSWORD is required (e.g. export TWINE_PASSWORD=$$GITEA_API_TOKEN)) +endif + $(VENV_PYTHON) -m twine upload --repository-url "$(GITEA_PYPI_REPOSITORY_URL)" dist/* # Test publication workflow using TestPyPI release-test: release-prepare @@ -1026,4 +1047,4 @@ release-rollback: $(VENV)/bin/activate echo " • Always test with TestPyPI first"; \ echo " • Use staging/preview environments"; \ echo " • Implement automated quality gates"; \ - echo " • Consider pre-release versions for testing" \ No newline at end of file + echo " • Consider pre-release versions for testing" diff --git a/README.md b/README.md index 0d2bf64..886f31b 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,21 @@ python3 -m build && make install-local source .venv/bin/activate # Required for each session ``` -**From PyPI (Coming Soon):** +**From Gitea PyPI (v1.1.0+):** ```bash -pip install kaizen-agentic # Available after v1.0.0 publication -# or -pipx install kaizen-agentic # Recommended for global CLI tools +export GITEA_PACKAGE_USER= +export GITEA_PACKAGE_TOKEN= + +pip install kaizen-agentic \ + --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" + +# or global CLI via pipx +pipx install kaizen-agentic \ + --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" ``` +See [docs/PACKAGE_RELEASE.md](docs/PACKAGE_RELEASE.md) for release and CI details. + ### Your First Project (New Users) **👋 New to Kaizen Agentic?** Follow our [Hello World Tutorial](docs/HELLO_WORLD_TUTORIAL.md) for a complete step-by-step guide. diff --git a/SCOPE.md b/SCOPE.md index 559f897..7402992 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -42,7 +42,7 @@ This repo is the canonical home for the **KaizenAgentic** operating model (`INTE - Project-specific implementation (agents guide work; they do not build the target software) - Custodian State Hub, MCP server code, or cross-domain governance (consumed, not owned) - Full KaizenGuidance codemod pipeline (vision in `wiki/KaizenGuidance.md`; not yet implemented) -- PyPI publication pipeline (v1.0.2 released locally; public PyPI distribution still pending) +- Gitea PyPI publication (`make publish-gitea`, tag workflow); public pypi.org optional --- @@ -163,4 +163,4 @@ keywords: [kaizen, intent, template, optimization, digital-talent-agency] ## Notes - `agents/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` (16 files) is what pip installs ship — coach, sys-medic, scope-analyst, and optimization are not yet bundled -- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality \ No newline at end of file +- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index bd19edc..d4c5bd3 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -57,16 +57,22 @@ make install-global # CLI available from any directory ``` -**Option D: From PyPI (Coming Soon)** +**Option D: From Gitea PyPI (v1.1.0+)** ```bash -# Will be available once v1.0.0 is published -pip install kaizen-agentic -# or -pipx install kaizen-agentic # Recommended for global CLI tools +export GITEA_PACKAGE_USER= +export GITEA_PACKAGE_TOKEN= + +pip install kaizen-agentic \ + --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" + +# or global CLI via pipx +pipx install kaizen-agentic \ + --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" ``` -> **📦 Release Status**: v1.0.0 is ready for publication. Use `make install-global` for system-wide availability. +> **📦 Registry**: Published on the Coulomb Gitea PyPI registry. Dependencies resolve +> from public PyPI via `--extra-index-url`. See [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md). ### 2. Verify Installation @@ -265,7 +271,9 @@ jobs: - uses: actions/setup-python@v4 with: python-version: '3.8' - - run: pip install kaizen-agentic + - run: >- + pip install kaizen-agentic + --extra-index-url "https://${{ secrets.GITEA_PACKAGE_USER }}:${{ secrets.GITEA_PACKAGE_TOKEN }}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" - run: kaizen-agentic validate ``` @@ -405,7 +413,8 @@ kaizen-agentic status # New team member setup git clone project-repo cd project-repo -pip install kaizen-agentic # or add to requirements +# see Option D for GITEA_PACKAGE_USER / GITEA_PACKAGE_TOKEN and --extra-index-url +pip install kaizen-agentic kaizen-agentic status # See what agents are used kaizen-agentic validate # Verify everything works @@ -419,12 +428,16 @@ cat CLAUDE.md **"Command not found: kaizen-agentic"** ```bash -# Install the package -pip install kaizen-agentic +# Install from Gitea PyPI (same credentials as Option D) +export GITEA_PACKAGE_USER= +export GITEA_PACKAGE_TOKEN= +pip install kaizen-agentic \ + --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" # Or if using virtual env: source .venv/bin/activate -pip install kaizen-agentic +pip install kaizen-agentic \ + --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" ``` **"No agents directory found"** @@ -463,4 +476,4 @@ Once you have agents installed: 4. **Share with team**: Document which agents your project uses 5. **Contribute back**: Report issues and suggest improvements -The key insight is that **you don't need the Makefile targets to use agents effectively** - the `kaizen-agentic` CLI provides all the functionality you need. The Makefile targets are just convenient shortcuts for projects that have them. \ No newline at end of file +The key insight is that **you don't need the Makefile targets to use agents effectively** - the `kaizen-agentic` CLI provides all the functionality you need. The Makefile targets are just convenient shortcuts for projects that have them. diff --git a/docs/PACKAGE_RELEASE.md b/docs/PACKAGE_RELEASE.md new file mode 100644 index 0000000..d0cf6d5 --- /dev/null +++ b/docs/PACKAGE_RELEASE.md @@ -0,0 +1,80 @@ +# Python Package Release + +`kaizen-agentic` publishes as the `kaizen-agentic` Python package on the Coulomb +Gitea PyPI registry. Public [pypi.org](https://pypi.org/) distribution is optional +and not required for ecosystem use. + +## Install (consumers) + +Dependencies such as `pyyaml` resolve from public PyPI. Use Gitea as an extra index: + +```bash +export GITEA_PACKAGE_USER= +export GITEA_PACKAGE_TOKEN= + +pip install kaizen-agentic \ + --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" +``` + +Global CLI via pipx: + +```bash +pipx install kaizen-agentic \ + --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/" +``` + +Do not commit tokenized index URLs. Inject credentials via environment variables or +CI secrets. + +## Local Release + +Build and validate artifacts: + +```bash +make package-check +``` + +Publish to the Coulomb organization registry: + +```bash +TWINE_USERNAME= \ +TWINE_PASSWORD= \ +make publish-gitea +``` + +Package upload endpoint: + +```text +https://gitea.coulomb.social/api/packages/coulomb/pypi +``` + +Consumer simple index: + +```text +https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/ +``` + +## Gitea Actions Release + +The `.gitea/workflows/publish-python-package.yml` workflow publishes on tags +matching `v*`. Configure these repository secrets before cutting a release: + +- `GITEA_PACKAGE_USER` +- `GITEA_PACKAGE_TOKEN` + +Example: + +```bash +git tag v1.2.0 +git push origin v1.2.0 +``` + +## Public PyPI (optional) + +When pypi.org credentials are configured (`~/.pypirc` or `TWINE_PASSWORD` API +token with `TWINE_USERNAME=__token__`): + +```bash +make release-publish +python -m twine upload dist/* +```