cogrind-workshop 0.1.0__tar.gz

cogrind_workshop-0.1.0/.github/workflows/dev-release.yml

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Dev release
+
+# On-demand PRE-RELEASE publish from `develop` — a dev build to exercise a candidate
+# before the real release. Manually triggered (workflow_dispatch; run it with
+# `--ref develop`, or via `git dev-release`). Publishes the `X.Y.Z.devN` version to
+# TestPyPI. It creates NO `v*` tag, so the real release.yml gate is untouched, and runs
+# no changelog job. See the handbook's releases.md ("Development versioning") + ci.md.
+#
+# cogrind-workshop is a pure CLI client — TestPyPI only, no GHCR/Docker image (its
+# release.yml has no docker job either).
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write       # TestPyPI trusted publishing (OIDC)
+
+jobs:
+  # Gate: dev builds come from develop and must carry a dev version.
+  gate:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.v.outputs.version }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Verify dev build from develop
+        id: v
+        run: |
+          if [ "$GITHUB_REF" != "refs/heads/develop" ]; then
+            echo "dev-release runs from develop only (got $GITHUB_REF)"; exit 1
+          fi
+          VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          case "$VERSION" in
+            *.dev*|*-dev) ;;
+            *) echo "version '$VERSION' is not a dev version (expected X.Y.Z.devN) — open the dev cycle first"; exit 1 ;;
+          esac
+          echo "dev version: $VERSION"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+  testpypi:
+    needs: gate
+    runs-on: ubuntu-latest
+    environment: testpypi   # matches the trusted-publisher config on TestPyPI
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

cogrind_workshop-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,134 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+  id-token: write       # PyPI trusted publishing
+
+# cogrind-workshop is a pure CLI client — PyPI only, no GHCR/Docker image
+# (unlike the MCP-server siblings). The job set is therefore gate → pypi →
+# changelog, with no docker job.
+
+jobs:
+  # Pre-flight checks. The publish job depends on this, so a failed gate
+  # prevents the artifact from shipping (no half-shipped state).
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0          # full history needed for the ancestor check below
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Verify tag matches pyproject version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PROJECT_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$PROJECT_VERSION" ]; then
+            echo "tag $TAG != pyproject $PROJECT_VERSION"
+            exit 1
+          fi
+
+      - name: Verify tag is reachable from origin/main
+        run: |
+          git fetch --no-tags origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "tagged commit $GITHUB_SHA is not on origin/main"
+            echo "release tags must come from main — back-merge through, then re-tag from main"
+            exit 1
+          fi
+
+  pypi:
+    needs: gate
+    runs-on: ubuntu-latest
+    environment: pypi   # matches the trusted-publisher config on PyPI
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # Generate the Highlights paragraph + categorized list, commit the new
+  # CHANGELOG.md section back to main, and create the GitHub Release. Runs
+  # AFTER pypi so the Release page points at an artifact that already
+  # exists. Two-phase invocation of generate_changelog.py keeps the LLM call
+  # to a single round-trip even though the commit-back happens onto a fresh
+  # main checkout.
+  changelog:
+    needs: [gate, pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # scoped here — only this job commits CHANGELOG.md back to main
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0          # full history + all tags for git-cliff
+          # default ref = the tag, which is what we want for `--mode=generate`
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Install git-cliff
+        uses: taiki-e/install-action@v2
+        with:
+          tool: git-cliff
+
+      - name: Generate release-body.md (LLM call happens here)
+        env:
+          # Set at the ParkviewLab org level — inherited by every repo
+          # under the org. Missing key → script writes a placeholder
+          # paragraph and the release still ships.
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_REF: ${{ github.ref }}
+        # `uv run --with anthropic` injects the SDK for just this invocation,
+        # without polluting pyproject.toml. Lets this workflow snippet be
+        # identical across every ParkviewLab repo regardless of whether
+        # `anthropic` is otherwise a project dep.
+        run: uv run --with anthropic python scripts/generate_changelog.py --mode=generate
+
+      - name: Switch to fresh origin/main and insert into CHANGELOG.md
+        run: |
+          # Stash the just-generated release body so it survives the checkout.
+          cp release-body.md /tmp/release-body.md
+          git fetch origin main
+          git checkout origin/main
+          mv /tmp/release-body.md release-body.md
+          # Re-runs only the file-manipulation half — no LLM call, no anthropic SDK needed.
+          uv run python scripts/generate_changelog.py --mode=insert
+
+      - name: Commit CHANGELOG.md back to main
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add CHANGELOG.md
+          if git diff --staged --quiet; then
+            echo "no changelog change to commit"
+            exit 0
+          fi
+          TAG="${GITHUB_REF#refs/tags/}"
+          # [skip ci] guards against any future non-tag-triggered workflows;
+          # this release workflow only fires on `push: tags` so isn't at risk
+          # of recursing, but the marker is cheap insurance.
+          git commit -m "docs(changelog): $TAG [skip ci]"
+          git push origin HEAD:main
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --notes-file release-body.md \
+            --target main

cogrind_workshop-0.1.0/.github/workflows/reuse.yml

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: REUSE
+
+# REUSE/SPDX compliance — a required check in every repo (code and docs).
+# See the handbook's licensing.md and ci.md.
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+
+permissions:
+  contents: read
+
+jobs:
+  reuse:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+      - name: reuse lint
+        run: uvx --from "reuse[charset-normalizer]" reuse lint

cogrind_workshop-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Test
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main, develop]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Sync deps
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Format check
+        run: uv run ruff format --check src tests
+
+      - name: Type check
+        run: uv run ty check          # ty must be a dev dependency
+
+      - name: Tests (excluding network + docling marker)
+        run: uv run pytest -m "not integration" -q

cogrind_workshop-0.1.0/.github/workflows/version-guard.yml

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Version guard
+
+# Feature PRs into `develop` must NOT change the version source-of-truth — the
+# bump happens at release, on `main` (see the handbook's releases.md / ci.md).
+# The release back-merge (main→develop) is a direct push, not a PR, so it is not
+# subject to this check.
+
+on:
+  pull_request:
+    branches: [develop]
+
+permissions:
+  contents: read
+
+jobs:
+  no-version-change:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Version SoT must be unchanged
+        env:
+          BASE: ${{ github.base_ref }}
+        run: |
+          git fetch --no-tags --depth=1 origin "$BASE"
+          fail=0
+          flag() { echo "::error::$1 changed in a feature PR — version bumps happen at release on main, not in feature work (handbook releases.md)."; fail=1; }
+          if [ -f VERSION.txt ]; then
+            old=$(git show "origin/$BASE:VERSION.txt" 2>/dev/null || echo "")
+            [ "$(cat VERSION.txt)" = "$old" ] || flag VERSION.txt
+          fi
+          if [ -f pyproject.toml ]; then
+            new=$(grep -E '^version *=' pyproject.toml | head -1 || true)
+            old=$(git show "origin/$BASE:pyproject.toml" 2>/dev/null | grep -E '^version *=' | head -1 || true)
+            [ "$new" = "$old" ] || flag "pyproject.toml [project].version"
+          fi
+          if [ -f package.json ]; then
+            new=$(grep -E '"version"' package.json | head -1 || true)
+            old=$(git show "origin/$BASE:package.json" 2>/dev/null | grep -E '"version"' | head -1 || true)
+            [ "$new" = "$old" ] || flag "package.json version"
+          fi
+          if [ "$fail" = 0 ]; then echo "version unchanged ✓"; fi
+          exit $fail

cogrind_workshop-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+.pytest_cache/
+.ruff_cache/
+.ty_cache/
+.mypy_cache/
+
+# Build
+build/
+dist/
+
+# venv / uv
+.venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.*
+
+# Transient release artifact: scripts/generate_changelog.py writes this for
+# `gh release create --notes-file`; it's regenerated every release, never committed.
+release-body.md

cogrind_workshop-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

cogrind_workshop-0.1.0/AGENTS.md

@@ -0,0 +1,29 @@
+<!--
+SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<!-- PARKVIEWLAB:BEGIN (managed by ParkviewLab/handbook — do not edit inside this block; run scripts/sync-agent-files.sh to update) -->
+# ParkviewLab conventions
+
+This repo follows the **[ParkviewLab handbook](https://github.com/ParkviewLab/handbook/tree/main)** —
+the single source of truth for how we work. These pointer files **don't re-inline** its rules:
+**read the handbook before non-trivial work**, starting with
+**[`ai-collaboration.md`](https://github.com/ParkviewLab/handbook/blob/main/docs/ai-collaboration.md)**
+(the behavioural contract). Only the safety-critical guardrails are summarized here.
+
+**If present, read `docs/northstar.md` before working.** It states the project's intent and is authoritative.
+
+## Shared-state writes need explicit authorization
+- **Merging a PR into `develop` is the user's call.** A broad directive ("fix all that", "finish it") authorizes work on the branch, **not** the merge.
+- **Tagging, cutting a release, force-pushing, or pushing to a protected branch each need an explicit, per-action go-ahead** — never inferred from a descriptive label (e.g. "→ v0.1.1"). One release ask covers the whole CLI release flow.
+
+## Workflow basics
+- Work in an ephemeral, **prefixed** worktree off `develop` (`feature-`/`fix-`/`doc-`/…) — don't commit on `develop`/`main` directly. Open a PR **into `develop`**.
+- PRs are **squash-merged**, so the **PR title** carries the Conventional Commit prefix (`feat:`/`fix:`/`docs:`/…) the changelog is generated from.
+
+**Everything else lives in the handbook** (don't rely on memory): branching, commits & changelogs, releases, Python tooling, CI, licensing, and the full communication norms — see <https://github.com/ParkviewLab/handbook/tree/main/docs>.
+<!-- PARKVIEWLAB:END -->
+
+<!-- Repo-specific guidance below this line is preserved by the sync script — add anything particular to this repo here. -->

cogrind_workshop-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project are recorded here. Each release entry
+has two parts:
+
+- **Highlights** — a 2-3 sentence "what's new" paragraph generated at
+  release time by an Anthropic-API call (see
+  `scripts/generate_changelog.py`).
+- **Categorized changes** — a list of merged commits since the previous
+  tag, grouped by [Conventional Commit](https://www.conventionalcommits.org/)
+  prefix, produced by [git-cliff](https://git-cliff.org/) using
+  `cliff.toml`.
+
+The release workflow on every tag push regenerates both, commits the new
+section here, and uses the same content as the GitHub Release body.
+
+<!--
+  Keep-a-Changelog ordering: [Unreleased] at the top, then newest
+  released version, then older versions. generate_changelog.py inserts
+  new "## [vX.Y.Z] - YYYY-MM-DD" sections directly below [Unreleased].
+  Don't remove the marker.
+-->
+
+## [Unreleased]

cogrind_workshop-0.1.0/CLAUDE.md

@@ -0,0 +1,29 @@
+<!--
+SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<!-- PARKVIEWLAB:BEGIN (managed by ParkviewLab/handbook — do not edit inside this block; run scripts/sync-agent-files.sh to update) -->
+# ParkviewLab conventions
+
+This repo follows the **[ParkviewLab handbook](https://github.com/ParkviewLab/handbook/tree/main)** —
+the single source of truth for how we work. These pointer files **don't re-inline** its rules:
+**read the handbook before non-trivial work**, starting with
+**[`ai-collaboration.md`](https://github.com/ParkviewLab/handbook/blob/main/docs/ai-collaboration.md)**
+(the behavioural contract). Only the safety-critical guardrails are summarized here.
+
+**If present, read `docs/northstar.md` before working.** It states the project's intent and is authoritative.
+
+## Shared-state writes need explicit authorization
+- **Merging a PR into `develop` is the user's call.** A broad directive ("fix all that", "finish it") authorizes work on the branch, **not** the merge.
+- **Tagging, cutting a release, force-pushing, or pushing to a protected branch each need an explicit, per-action go-ahead** — never inferred from a descriptive label (e.g. "→ v0.1.1"). One release ask covers the whole CLI release flow.
+
+## Workflow basics
+- Work in an ephemeral, **prefixed** worktree off `develop` (`feature-`/`fix-`/`doc-`/…) — don't commit on `develop`/`main` directly. Open a PR **into `develop`**.
+- PRs are **squash-merged**, so the **PR title** carries the Conventional Commit prefix (`feat:`/`fix:`/`docs:`/…) the changelog is generated from.
+
+**Everything else lives in the handbook** (don't rely on memory): branching, commits & changelogs, releases, Python tooling, CI, licensing, and the full communication norms — see <https://github.com/ParkviewLab/handbook/tree/main/docs>.
+<!-- PARKVIEWLAB:END -->
+
+<!-- Repo-specific guidance below this line is preserved by the sync script — add anything particular to this repo here. -->