feat: prepare duckflow for PyPI submission

.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+# Copyright (C) 2026 Gregory R. Warnes
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade pip build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Check distribution with twine
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/duckflow/
+    permissions:
+      id-token: write  # required for Trusted Publisher (OIDC)
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-09
+
+### Added
+- Initial release of `duckflow`.
+- `DuckflowEntry` dataclass for normalized annotation data.
+- `extract_duckflow_entries_from_text` for parsing inline JSON annotations from
+  source comments (`#`, `//`, `/* */` styles).
+- `extract_duckflow_entries` for recursive source-tree scanning.
+- `iter_source_files` with configurable glob patterns and exclude-parts.
+- `filter_entries` for substring-based filtering across all fields.
+- `stitch_duckflow` to build a control/data-flow graph from local facts.
+- `render_mermaid` to emit a Mermaid `flowchart TD` diagram.
+- `duckflow-extract` and `duckflow-mermaid` CLI entry points.
+- Mandatory UTC `timestamp` validation on every annotation.
+
+[Unreleased]: https://github.com/Warnes-Innovations/duckflow/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Warnes-Innovations/duckflow/releases/tag/v0.1.0

README.md

@@ -1,5 +1,9 @@
 # Duckflow
 
+[![PyPI version](https://img.shields.io/pypi/v/duckflow.svg)](https://pypi.org/project/duckflow/)
+[![Python versions](https://img.shields.io/pypi/pyversions/duckflow.svg)](https://pypi.org/project/duckflow/)
+[![License: AGPL v3+](https://img.shields.io/badge/License-AGPL%20v3%2B-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+
 `duckflow` is a lightweight annotation format and toolkit for tracing data flow through source code using local, comment-based facts.
 
 The split is intentional:
@@ -81,6 +85,14 @@ The extractor and Mermaid generator build edges from local facts only:
 
 ## Installation
 
+Install from PyPI:
+
+```bash
+pip install duckflow
+```
+
+Or install from source for development:
+
 ```bash
 python -m venv .venv
 source .venv/bin/activate

pyproject.toml

@@ -8,27 +8,44 @@ version = "0.1.0"
 description = "Comment-based data-flow extraction and Mermaid rendering"
 readme = "README.md"
 requires-python = ">=3.10"
-license = { text = "AGPL-3.0-or-later" }
+license = "AGPL-3.0-or-later"
 authors = [
   { name = "Gregory R. Warnes" }
 ]
+keywords = [
+  "dataflow",
+  "code-annotation",
+  "mermaid",
+  "static-analysis",
+  "architecture",
+]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+  "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Documentation",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
 ]
 
+[project.urls]
+Homepage = "https://github.com/Warnes-Innovations/duckflow"
+Source = "https://github.com/Warnes-Innovations/duckflow"
+"Bug Tracker" = "https://github.com/Warnes-Innovations/duckflow/issues"
+Changelog = "https://github.com/Warnes-Innovations/duckflow/blob/main/CHANGELOG.md"
+
 [project.scripts]
 duckflow-extract = "duckflow.cli:extract_main"
 duckflow-mermaid = "duckflow.cli:mermaid_main"
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0"]
+dev = ["pytest>=8.0", "build>=1.0", "twine>=5.0"]
 
 [tool.setuptools.packages.find]
 include = ["duckflow*"]