chronocratic-models 0.1.0a1__tar.gz

chronocratic_models-0.1.0a1/.github/workflows/auto-changelog-fragment.yml

@@ -0,0 +1,128 @@
+name: Changelog fragment
+
+# Single source of truth for changelog fragments on PRs targeting `dev`:
+#   1. Same-repo PR with no fragment  -> create one from the PR title and push it.
+#   2. Always (incl. fork PRs)         -> `towncrier check` so every PR has a fragment.
+#
+# Both happen in one job so the check sees the freshly-created fragment in the
+# same run. A push made with GITHUB_TOKEN does NOT re-trigger workflows, so the
+# check must not live in a separate workflow that never re-runs after the push.
+#
+# Fork PRs cannot be pushed to, so they are only checked — the contributor must
+# add a fragment by hand (or a maintainer pushes one to the PR branch).
+#
+# Label convention for fragment type (defaults to `changed`):
+#   changelog:added | changelog:fixed | changelog:changed
+#   changelog:removed | changelog:deprecated | changelog:security
+# `skip-changelog` opts the PR out entirely.
+
+on:
+  pull_request:
+    branches: [dev]
+    types: [opened, edited, synchronize, labeled, unlabeled]
+
+permissions:
+  contents: write
+
+jobs:
+  fragment:
+    name: Changelog fragment
+    runs-on: ubuntu-latest
+    # Skip release-prep PRs two ways: the `skip-changelog` label (may be missing
+    # if the PR was opened by hand) AND the `release-prep/*` head branch, which is
+    # always present in the event payload regardless of labelling.
+    if: >-
+      !contains(github.event.pull_request.labels.*.name, 'skip-changelog') &&
+      !startsWith(github.event.pull_request.head.ref, 'release-prep/')
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # For same-repo PRs check out the head branch so we can commit + push
+          # a fragment. For forks this ref is still readable for the check step.
+          ref: ${{ github.event.pull_request.head.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install towncrier
+        run: pip install towncrier
+
+      - name: Check if a fragment already exists
+        id: check
+        env:
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          if compgen -G "changelog.d/${PR}.*.md" > /dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # A `changelog:<type>` label wins; otherwise infer from the Conventional
+      # Commits prefix of the PR title; otherwise fall back to `changed`.
+      - name: Resolve fragment type
+        if: steps.check.outputs.exists == 'false'
+        id: type
+        env:
+          LABELS: ${{ toJSON(github.event.pull_request.labels.*.name) }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          TYPE=""
+          if   echo "$LABELS" | grep -q '"changelog:added"';      then TYPE="added"
+          elif echo "$LABELS" | grep -q '"changelog:fixed"';      then TYPE="fixed"
+          elif echo "$LABELS" | grep -q '"changelog:changed"';    then TYPE="changed"
+          elif echo "$LABELS" | grep -q '"changelog:removed"';    then TYPE="removed"
+          elif echo "$LABELS" | grep -q '"changelog:deprecated"'; then TYPE="deprecated"
+          elif echo "$LABELS" | grep -q '"changelog:security"';   then TYPE="security"
+          fi
+
+          if [ -z "$TYPE" ]; then
+            # Lowercase Conventional Commits verb before the first ( or : or !
+            PREFIX="$(printf '%s' "$PR_TITLE" | sed -E 's/^([a-zA-Z]+).*/\1/' | tr '[:upper:]' '[:lower:]')"
+            case "$PREFIX" in
+              fix)                       TYPE="fixed" ;;
+              feat)                      TYPE="added" ;;
+              revert|remove)             TYPE="removed" ;;
+              deprecate)                 TYPE="deprecated" ;;
+              security)                  TYPE="security" ;;
+              refactor|perf|change)      TYPE="changed" ;;
+              *)                         TYPE="changed" ;;
+            esac
+          fi
+
+          echo "type=$TYPE" >> "$GITHUB_OUTPUT"
+
+      # Only same-repo PRs can be pushed to. Forks fall through to the check
+      # step, which fails until the contributor adds a fragment by hand.
+      - name: Create and commit fragment
+        if: >-
+          steps.check.outputs.exists == 'false' &&
+          github.event.pull_request.head.repo.full_name == github.repository
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          FRAGMENT_TYPE: ${{ steps.type.outputs.type }}
+        run: |
+          # Strip a leading Conventional Commits prefix (e.g. "ci(changelog): ")
+          # so the changelog reads as user-facing prose, then capitalise and
+          # ensure a single trailing period.
+          BODY="$(printf '%s' "${PR_TITLE}" | sed -E 's/^[a-z]+(\([^)]*\))?!?:[[:space:]]*//')"
+          BODY="$(printf '%s' "${BODY}" | awk '{ print toupper(substr($0,1,1)) substr($0,2) }')"
+          BODY="${BODY%.}."
+
+          FRAGMENT="changelog.d/${PR_NUMBER}.${FRAGMENT_TYPE}.md"
+          printf '%s\n' "${BODY}" > "${FRAGMENT}"
+
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add "${FRAGMENT}"
+          git commit -m "ci: add towncrier fragment for PR #${PR_NUMBER}"
+          git push
+
+      - name: Verify a fragment is present
+        run: towncrier check --compare-with origin/${{ github.base_ref }}

chronocratic_models-0.1.0a1/.github/workflows/build-and-test.yml

@@ -0,0 +1,80 @@
+name: Build and Test
+
+on:
+  pull_request:
+    branches: [main, dev]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        run: pip install uv
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Run tests
+        run: uv run pytest tests/ --cov=src/chronocratic/models --cov-report=xml
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install ruff
+      - name: Run ruff check
+        run: ruff check src/
+      - name: Run ruff format check
+        run: ruff format --check src/ tests/
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Validate with twine
+        run: pip install twine && twine check dist/*
+
+  docs:
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        run: pip install uv
+      - name: Install dependencies
+        run: uv sync --extra docs
+      - name: Build docs
+        run: uv run sphinx-build -b html docs/ docs/_build/

chronocratic_models-0.1.0a1/.github/workflows/ff-merge-check.yml

@@ -0,0 +1,46 @@
+name: Check Fast-Forward
+
+on:
+  issue_comment:
+    types: [created]
+
+jobs:
+  check-fast-forward:
+    if: ${{ contains(github.event.comment.body, '/check-fast-forward')
+            && github.event.issue.pull_request }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+    steps:
+      - name: Verify target branch
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const { data: pr } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number
+            });
+            if (pr.base.ref !== 'main' || pr.head.ref !== 'dev') {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: `❌ \`/check-fast-forward\` only works on \`dev → main\` PRs `
+                    + `(this PR: \`${pr.head.ref} → ${pr.base.ref}\`).`
+              });
+              core.setFailed('Fast-forward check is only allowed for dev → main PRs.');
+            }
+
+      - name: Checkout repo
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Check if fast-forward is possible
+        uses: sequoia-pgp/fast-forward@v1
+        with:
+          merge: false
+          comment: always

chronocratic_models-0.1.0a1/.github/workflows/ff-merge-do.yml

@@ -0,0 +1,98 @@
+name: Fast Forward Merge
+
+on:
+  issue_comment:
+    types: [created]
+
+concurrency:
+  group: fast-forward-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  fast-forward:
+    if: ${{ contains(github.event.comment.body, '/fast-forward')
+            && github.event.issue.pull_request }}
+    runs-on: ubuntu-latest
+    # The FF_MERGE_TOKEN secret lives in the `ff_merge` environment. It is a PAT
+    # of a ruleset bypass actor — the GITHUB_TOKEN (github-actions[bot]) is not on
+    # the main ruleset bypass list, so its push to main is rejected.
+    environment: ff_merge
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.FF_MERGE_TOKEN }}
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Verify PR and actor permissions
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const { data: pr } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number
+            });
+            if (pr.base.ref !== 'main') {
+              core.setFailed('Fast-forward is only allowed for PRs targeting main.');
+            }
+            if (pr.head.ref !== 'dev') {
+              core.setFailed('Fast-forward is only allowed for PRs from dev to main.');
+            }
+            const { data: perm } = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              username: context.actor
+            });
+            if (!['admin', 'maintain'].includes(perm.permission)) {
+              core.setFailed(`@${context.actor} (role: ${perm.permission}) — only admin/maintainer can fast-forward.`);
+            }
+
+      # Disabled while repo is a personal fork with no org reviewers — a
+      # solo maintainer cannot approve their own PR. Re-enable once moved
+      # to an org with a second reviewer (or branch-protection approval rule).
+      # - name: Check PR is approved
+      #   uses: actions/github-script@v9
+      #   with:
+      #     script: |
+      #       const { data: reviews } = await github.rest.pulls.listReviews({
+      #         owner: context.repo.owner,
+      #         repo: context.repo.repo,
+      #         pull_number: context.issue.number
+      #       });
+      #       const approved = reviews.filter(r => r.state === 'APPROVED');
+      #       if (approved.length === 0) {
+      #         core.setFailed('PR must have at least one approval before fast-forward merge.');
+      #       }
+
+      - name: Backup main before merge
+        run: |
+          BACKUP="main.backup.${{ github.event.issue.number }}.$(date +%Y%m%d-%H%M%S)"
+          git branch "$BACKUP" origin/main
+          git push origin "$BACKUP"
+          echo "Created backup: $BACKUP"
+
+      - name: Fast-forward merge
+        uses: sequoia-pgp/fast-forward@v1
+        with:
+          merge: true
+          comment: always
+          github_token: ${{ secrets.FF_MERGE_TOKEN }}
+
+      - name: Clean up old backups
+        run: |
+          git fetch --prune origin
+          # Sort by the trailing YYYYMMDD-HHMMSS timestamp (4th dot field) so
+          # retention is chronological regardless of PR-number digit width.
+          git branch -r | grep 'origin/main.backup.' | sed 's| *origin/||' | \
+            sort -t. -k4 | head -n -5 | \
+            xargs -I {} git push origin --delete {} || true

chronocratic_models-0.1.0a1/.github/workflows/main-pre-merge-gate.yml

@@ -0,0 +1,61 @@
+name: Main Pre-merge Gate
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: pre-merge-gate-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  forbidden-files:
+    name: Check forbidden paths
+    runs-on: ubuntu-latest
+    steps:
+      - name: Reject non-dev PRs
+        if: ${{ github.head_ref != 'dev' }}
+        run: |
+          echo "::error::PRs from '${{ github.head_ref }}' to main are not allowed. Only dev→main merges are permitted."
+          exit 1
+
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Scan PR for forbidden files
+        run: |
+          FORBIDDEN=(
+            ".claude/"
+            ".remember/"
+            ".planning/"
+            "MEMORY.md"
+            "CLAUDE.md"
+            "CONTEXT.md"
+            "STATE.md"
+            "ROADMAP.md"
+            ".continue-here.md"
+            "HANDOFF.json"
+          )
+
+          CHANGED=$(git diff --diff-filter=ACMR --name-only ${{ github.event.pull_request.base.sha }}..HEAD)
+          MATCHED=()
+
+          for path in "${FORBIDDEN[@]}"; do
+            # Anchor to a path boundary (start of path or after a '/') so e.g.
+            # CLAUDE.md does not match NOTCLAUDE.md.
+            while IFS= read -r f; do
+              [ -n "$f" ] && MATCHED+=("$f")
+            done < <(printf '%s\n' "$CHANGED" | grep -E "(^|/)$path" || true)
+          done
+
+          if [ "${#MATCHED[@]}" -gt 0 ]; then
+            echo "::error::Forbidden files detected:"
+            for f in "${MATCHED[@]}"; do
+              echo "::error::  - $f"
+            done
+            exit 1
+          fi
+          echo "All clear."

chronocratic_models-0.1.0a1/.github/workflows/pypi-publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/chronocratic-models
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

chronocratic_models-0.1.0a1/.github/workflows/release-notes.yml

@@ -0,0 +1,44 @@
+name: Sync release notes
+
+# When a GitHub release is published, replace its body with the matching
+# section from CHANGELOG.md so the repo, GitHub, and Read the Docs all show
+# identical notes. CHANGELOG.md is assembled from towncrier fragments on `dev`
+# before the release, so the section already exists at tag time.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    name: Sync notes from CHANGELOG.md
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: main
+          fetch-depth: 0
+
+      - name: Extract changelog section
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          VERSION="${TAG#v}"
+          awk -v v="$VERSION" '
+            index($0, "## v" v " ") == 1 { f = 1; print; next }
+            f && /^## v/ { exit }
+            f { print }
+          ' CHANGELOG.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "::error::No CHANGELOG.md section found for $TAG (expected a '## v$VERSION ' heading)."
+            exit 1
+          fi
+          echo "Extracted notes for $TAG:"
+          cat release-notes.md
+
+      - name: Update release body
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release edit "${{ github.event.release.tag_name }}" --notes-file release-notes.md

chronocratic_models-0.1.0a1/.github/workflows/release-prep.yml

@@ -0,0 +1,83 @@
+name: Release prep
+
+# Assembles CHANGELOG.md from the accumulated towncrier fragments on `dev`,
+# BEFORE the release. Run this, merge the resulting PR into `dev`, then open
+# the dev -> main PR and fast-forward it (`/fast-forward`). The dev -> main
+# merge cannot build the changelog itself: that merge is fast-forward only,
+# so main must equal dev's exact HEAD — every commit has to already be on dev.
+#
+# Versioning is dynamic (setuptools_scm), so the version is supplied here and
+# only stamps the changelog heading; the real release version is the git tag
+# created when the GitHub release is published.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version, no leading v (e.g. 0.1.0a2)"
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prep:
+    name: Build changelog and open PR
+    runs-on: ubuntu-latest
+    # FF_MERGE_TOKEN (PAT, in the `ff_merge` environment) acts as a real user, so
+    # it can open the PR — the GITHUB_TOKEN is blocked by the repo's "Allow GitHub
+    # Actions to create and approve pull requests" policy being off.
+    environment: ff_merge
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: dev
+          fetch-depth: 0
+          token: ${{ secrets.FF_MERGE_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install towncrier
+        run: pip install towncrier
+
+      - name: Validate version
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([ab]|rc)?[0-9]*$'; then
+            echo "::error::'$VERSION' is not a valid PEP 440 version (expected e.g. 0.1.0 or 0.1.0a2)."
+            exit 1
+          fi
+          if [ -z "$(ls -A changelog.d/*.md 2>/dev/null | grep -v '/README.md')" ]; then
+            echo "::error::No towncrier fragments in changelog.d/ — nothing to release."
+            exit 1
+          fi
+
+      - name: Build changelog
+        env:
+          VERSION: ${{ inputs.version }}
+        run: towncrier build --yes --version "$VERSION"
+
+      - name: Open release-prep PR
+        env:
+          VERSION: ${{ inputs.version }}
+          GH_TOKEN: ${{ secrets.FF_MERGE_TOKEN }}
+        run: |
+          BRANCH="release-prep/v${VERSION}"
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add -A
+          git commit -m "docs(changelog): assemble notes for v${VERSION}"
+          git push -u origin "$BRANCH"
+          gh pr create \
+            --base dev \
+            --head "$BRANCH" \
+            --title "docs(changelog): release v${VERSION}" \
+            --label skip-changelog \
+            --body "Auto-generated by the release-prep workflow. Builds \`CHANGELOG.md\` from the towncrier fragments and removes them. Merge into \`dev\`, then open the dev -> main PR."