feat: update project structure and documentation

.github/workflows/ci.yml

@@ -0,0 +1,118 @@
+name: CI
+
+# Runs on every Git Flow branch type so quality gates are enforced everywhere:
+#   feature/* — new features branched from develop
+#   release/* — release-prep branches branched from develop
+#   hotfix/*  — production patch branches branched from main
+#   develop   — integration branch (also PR target for features)
+#   main      — production branch (PR target for release/* and hotfix/*)
+
+on:
+  push:
+    branches:
+      - develop
+      - "feature/**"
+      - "release/**"
+      - "hotfix/**"
+  pull_request:
+    branches:
+      - main
+      - develop
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ------------------------------------------------------------------
+  # 1. Test matrix — Python 3.9 / 3.11 / 3.13
+  # ------------------------------------------------------------------
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and test deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+
+      # Run only the fast build-system tests in CI.
+      # test_generator.py creates real venvs per test (~10 s each);
+      # run it locally before opening a PR: python -m pytest tests/
+      - name: Run build-system tests
+        run: python -m pytest tests/test_build_system.py -v --tb=short
+
+  # ------------------------------------------------------------------
+  # 2. Build verification — confirms the package builds and passes
+  #    twine's metadata checks before any merge
+  # ------------------------------------------------------------------
+  build-check:
+    name: Build verification
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+          cache: pip
+
+      - name: Install build tooling
+        run: python -m pip install build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Verify distributions with twine
+        run: python -m twine check dist/*
+
+  # ------------------------------------------------------------------
+  # 3. Release-branch extra check — version consistency gate.
+  #    Only runs on release/* and hotfix/* to catch version drift
+  #    before a merge to main triggers the PyPI publish.
+  # ------------------------------------------------------------------
+  version-check:
+    name: Version consistency
+    runs-on: ubuntu-latest
+    if: |
+      startsWith(github.ref, 'refs/heads/release/') ||
+      startsWith(github.ref, 'refs/heads/hotfix/')  ||
+      (github.event_name == 'pull_request' && github.base_ref == 'main')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Check version consistency across files
+        run: |
+          INIT_VER=$(python -c "import re, pathlib; m=re.search(r'__version__\s*=\s*\"([^\"]+)\"', pathlib.Path('auto_gen_py_project/__init__.py').read_text()); print(m.group(1))")
+          SETUP_VER=$(python -c "import re, pathlib; m=re.search(r'version=\"([^\"]+)\"', pathlib.Path('setup.py').read_text()); print(m.group(1))")
+          echo "  __init__.py : $INIT_VER"
+          echo "  setup.py    : $SETUP_VER"
+          if [ "$INIT_VER" != "$SETUP_VER" ]; then
+            echo "ERROR: Version mismatch between __init__.py ($INIT_VER) and setup.py ($SETUP_VER)"
+            exit 1
+          fi
+          echo "OK: versions match ($INIT_VER)"

.github/workflows/release.yml

@@ -0,0 +1,111 @@
+name: Release & Publish
+
+# Triggered when a GitHub Release is published.
+# By Git Flow convention a release is created only after a release/* or
+# hotfix/* branch is merged into main and the commit is tagged.
+#
+# Workflow:
+#   1. Build source distribution + wheel.
+#   2. Publish to PyPI via OIDC Trusted Publisher (no API token required).
+#
+# Required GitHub settings:
+#   - Environment named "pypi" with a Trusted Publisher configured at
+#     https://pypi.org/manage/account/publishing/
+#   - id-token: write permission (granted below per job)
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+env:
+  PYTHON_VERSION: "3.x"
+  DIST_DIR: dist
+
+jobs:
+  # ------------------------------------------------------------------
+  # 1. Run tests one final time on the tagged commit before publishing
+  # ------------------------------------------------------------------
+  pre-publish-test:
+    name: Pre-publish tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: Install package and test deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+
+      - name: Run tests
+        run: python -m pytest tests/test_build_system.py -v --tb=short
+
+  # ------------------------------------------------------------------
+  # 2. Build distributions
+  # ------------------------------------------------------------------
+  release-build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    needs: pre-publish-test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: ${{ env.DIST_DIR }}/
+
+  # ------------------------------------------------------------------
+  # 3. Publish to PyPI
+  # ------------------------------------------------------------------
+  pypi-publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release-build
+
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/auto-gen-py-project/${{ github.event.release.tag_name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: ${{ env.DIST_DIR }}/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: ${{ env.DIST_DIR }}/

.gitignore

@@ -6,4 +6,5 @@ auto_gen_py_project.egg-info/
 
 *.pyc
 .env
-CLAUDE.md
+CLAUDE.md
+.claude/