toolframe-testkit 0.1.2__tar.gz → 0.2.0__tar.gz

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: Validate Python distribution
 
 on:
   push:
-    branches: ['**']
+    branches: [main]
   pull_request:
   workflow_dispatch:
   workflow_call:

toolframe_testkit-0.2.0/.github/workflows/quality.yml

@@ -0,0 +1,63 @@
+name: Code quality
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  branch-policy:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.14.7'
+      - name: Check the actual source branch
+        env:
+          BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
+        run: python scripts/check_branch_name.py "$BRANCH_NAME"
+
+  code-quality:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: '0.12.8'
+          enable-cache: false
+      - name: Check Python lint and formatting
+        run: uvx prek==0.5.5 run ruff-check ruff-format --all-files --show-diff-on-failure
+
+  commit-policy:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.14.7'
+      - uses: commit-check/commit-check-action@a61779784a953fd9047c001c102cfeac5cf26964 # commit-check 2.18.3
+        with:
+          message: true
+          branch: false
+          pr-title: true
+          pr-comments: false

toolframe_testkit-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+default_install_hook_types: [pre-commit, commit-msg]
+default_stages: [pre-commit]
+default_language_version:
+  python: python3.11
+
+repos:
+  - repo: local
+    hooks:
+      - id: check-branch-name
+        name: Check branch naming policy
+        entry: python scripts/check_branch_name.py
+        language: python
+        always_run: true
+        pass_filenames: false
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.0
+    hooks:
+      - id: ruff-check
+        types_or: [python, pyi]
+        files: '^(src|tests|scripts)/'
+      - id: ruff-format
+        types_or: [python, pyi]
+        args: [--check]
+        files: '^(src|tests|scripts)/'
+  - repo: https://github.com/commit-check/commit-check
+    rev: v2.18.3
+    hooks:
+      - id: check-message
+        stages: [commit-msg]

toolframe_testkit-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+## Commit hooks
+
+Install [prek](https://prek.j178.dev/) and enable the repository's hooks:
+
+```sh
+uv tool install prek==0.5.5
+prek install --allow-missing-config
+prek run --all-files
+```
+
+The missing-config option allows older worktrees without this configuration to
+keep working. Worktrees containing `.pre-commit-config.yaml` still run the checks.
+The `pre-commit` hook checks the branch name, Python lint, and formatting. The
+`commit-msg` hook checks Conventional Commits. Both Ruff hooks only check files;
+they do not rewrite a commit's contents. Fix lint and formatting explicitly:
+
+```sh
+uvx ruff==0.17.0 check --fix src tests scripts
+uvx ruff==0.17.0 format src tests scripts
+prek run --all-files
+```
+
+The Ruff version and checked paths are pinned in
+[the hook configuration](.pre-commit-config.yaml); the Python rules remain in
+[pyproject.toml](pyproject.toml). CI uses these same hooks on all tracked files
+within their configured paths. Existing package, integration, and release checks
+run independently.
+
+## Branches and commits
+
+[cchk.toml](cchk.toml) defines the allowed branch and commit types. Work branches
+use `feat/`, `fix/`, `release/`, or `chore/`, followed by lowercase ASCII letters
+and digits separated by single hyphens. Release versions may also contain dots,
+as in `release/v1.2.0-rc.1`; every separator must have an alphanumeric character on
+both sides. The default branch `main` is the standalone exception.
+
+Commit types are independent of branch types: for example,
+`docs: clarify setup` is valid on `chore/update-docs`. Commit-check uses Conventional
+Commits with its default subject length of 5–80 characters. Pull requests check
+their commits and title so the title can be used for a Conventional Commit when
+squash merging.
+
+Local hooks can be bypassed. CI reports `branch-policy`, `code-quality`, and
+`commit-policy`; maintainers must configure required status checks separately to
+make passing checks a merge requirement.
+
+For package setup and broader verification, see [the development guide](docs/development.md).

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: toolframe-testkit
-Version: 0.1.2
+Version: 0.2.0
 Summary: Public contract checks and installed-application tests for Toolframe developers
 Project-URL: Homepage, https://github.com/toolframe/toolframe-testkit
 Project-URL: Repository, https://github.com/toolframe/toolframe-testkit
@@ -15,7 +15,7 @@ Requires-Dist: jsonschema<5,>=4.23
 Requires-Dist: psutil<9,>=7
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: tomlkit<1,>=0.13
-Requires-Dist: toolframe-sdk==0.3.0
+Requires-Dist: toolframe-sdk==0.4.0
 Provides-Extra: pytest
 Requires-Dist: pytest<10,>=8; extra == 'pytest'
 Description-Content-Type: text/markdown
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
 Toolframe testkit is a Python library for checking a plugin's public SDK contract
 and exercising an installed Toolframe Core application through its public CLI and
 HTTP APIs. It is a developer test dependency, not a Core runtime plugin. Version
-0.1.2 supports Python 3.14 or newer and pins `toolframe-sdk==0.3.0`.
+0.2.0 supports Python 3.14 or newer and pins `toolframe-sdk==0.4.0`.
 
 The package is Apache-2.0 licensed. It does not install Core, choose a global
 application, or load a pytest plugin automatically.
@@ -35,7 +35,7 @@ application, or load a pytest plugin automatically.
 Install the checker and opt-in pytest integration from PyPI:
 
 ```sh
-python -m pip install 'toolframe-testkit[pytest]==0.1.2'
+python -m pip install 'toolframe-testkit[pytest]==0.2.0'
 ```
 
 The SDK is installed as a dependency. See
@@ -106,3 +106,5 @@ remote deployments. It redacts its owned management token and common bearer/toke
 query forms, but cannot guarantee redaction of arbitrary plugin output.
 
 For release validation and Trusted Publisher setup, see [releasing](docs/releasing.md).
+
+For development hooks and contribution rules, see [Contributing](CONTRIBUTING.md).

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/README.md

@@ -3,7 +3,7 @@
 Toolframe testkit is a Python library for checking a plugin's public SDK contract
 and exercising an installed Toolframe Core application through its public CLI and
 HTTP APIs. It is a developer test dependency, not a Core runtime plugin. Version
-0.1.2 supports Python 3.14 or newer and pins `toolframe-sdk==0.3.0`.
+0.2.0 supports Python 3.14 or newer and pins `toolframe-sdk==0.4.0`.
 
 The package is Apache-2.0 licensed. It does not install Core, choose a global
 application, or load a pytest plugin automatically.
@@ -13,7 +13,7 @@ application, or load a pytest plugin automatically.
 Install the checker and opt-in pytest integration from PyPI:
 
 ```sh
-python -m pip install 'toolframe-testkit[pytest]==0.1.2'
+python -m pip install 'toolframe-testkit[pytest]==0.2.0'
 ```
 
 The SDK is installed as a dependency. See
@@ -84,3 +84,5 @@ remote deployments. It redacts its owned management token and common bearer/toke
 query forms, but cannot guarantee redaction of arbitrary plugin output.
 
 For release validation and Trusted Publisher setup, see [releasing](docs/releasing.md).
+
+For development hooks and contribution rules, see [Contributing](CONTRIBUTING.md).

toolframe_testkit-0.2.0/cchk.toml

@@ -0,0 +1,10 @@
+[commit]
+conventional_commits = true
+allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore", "perf", "build", "ci"]
+
+[branch]
+conventional_branch = true
+allow_branch_types = ["feat", "fix", "release", "chore"]
+allow_branch_names = ["main"]
+# scripts/check_branch_name.py enforces these names literally, without the
+# additional standalone branch exceptions built into commit-check.

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/docs/development.md

@@ -1,10 +1,9 @@
 # Development and verification
 
 The testkit repository is independently buildable. Runtime dependencies are
-`toolframe-sdk==0.3.0`, `httpx`, `tomlkit`, `psutil`, `pydantic`, and `jsonschema`;
+`toolframe-sdk==0.4.0`, `httpx`, `tomlkit`, `psutil`, `pydantic`, and `jsonschema`;
 pytest is available
-through the `[pytest]` extra. Python 3.14 or newer is required. No release is
-published yet, so consumer-style installation uses a local wheelhouse.
+through the `[pytest]` extra. Python 3.14 or newer is required. Consumer-style installation can use PyPI or an explicitly built local wheelhouse.
 
 ## Local environment
 
@@ -13,7 +12,7 @@ install the package with the development tools. The install must use the
 wheelhouse so uv does not select an unrelated source checkout:
 
 ```sh
-mkdir -p .local/wheelhouse
+mkdir -p build/wheelhouse
 ```
 
 When testing sibling development checkouts, build their wheels into a local,
@@ -21,15 +20,15 @@ ignored wheelhouse. These commands are for a sibling checkout layout and are
 deliberately explicit about `--no-sources`:
 
 ```sh
-uv build --no-sources --wheel --out-dir .local/wheelhouse \
+uv build --no-sources --wheel --out-dir build/wheelhouse \
   ../toolframe-sdk/.worktrees/plugin-services
-uv build --no-sources --wheel --out-dir .local/wheelhouse \
+uv build --no-sources --wheel --out-dir build/wheelhouse \
   ../fastapi-cordis
-uv build --no-sources --wheel --out-dir .local/wheelhouse \
-  ../toolframe-core/.worktrees/plugin-services
-uv build --no-sources --wheel --out-dir .local/wheelhouse \
-  ../toolframe-storage-sqlite
-uv build --no-sources --wheel --out-dir .local/wheelhouse \
+uv build --no-sources --wheel --out-dir build/wheelhouse \
+  ../toolframe-core
+uv build --no-sources --wheel --out-dir build/wheelhouse \
+  ../toolframe-sql-sqlite
+uv build --no-sources --wheel --out-dir build/wheelhouse \
   tests/assets/service-plugin
 ```
 
@@ -39,7 +38,7 @@ SDK wheel, install the development environment:
 
 ```sh
 uv venv .venv
-uv pip install --python .venv/bin/python --find-links .local/wheelhouse \
+uv pip install --python .venv/bin/python --find-links build/wheelhouse \
   -e '.[pytest]' pytest ruff build hatchling
 ```
 
@@ -71,16 +70,16 @@ Install the matching Core command into the same environment after its Core,
 Cordis, and SDK wheels are in the wheelhouse:
 
 ```sh
-uv pip install --python .venv/bin/python --find-links .local/wheelhouse \
-  toolframe-core==0.6.2
+uv pip install --python .venv/bin/python --find-links build/wheelhouse \
+  toolframe-core==0.7.0
 ```
 
 ```sh
-export TOOLFRAME_TESTKIT_STORAGE_WHEEL="$PWD/.local/wheelhouse/toolframe_storage_sqlite-0.3.0-py3-none-any.whl"
-export TOOLFRAME_TESTKIT_FIXTURE_WHEEL="$PWD/.local/wheelhouse/toolframe_testkit_fixture-0.1.0-py3-none-any.whl"
+export TOOLFRAME_TESTKIT_STORAGE_WHEEL="$PWD/build/wheelhouse/toolframe_sql_sqlite-0.4.0-py3-none-any.whl"
+export TOOLFRAME_TESTKIT_FIXTURE_WHEEL="$PWD/build/wheelhouse/toolframe_testkit_fixture-0.1.0-py3-none-any.whl"
 .venv/bin/python -m pytest tests/test_installed_core.py \
   --toolframe-core-command "$PWD/.venv/bin/toolframe-core" \
-  --toolframe-find-links "$PWD/.local/wheelhouse" \
+  --toolframe-find-links "$PWD/build/wheelhouse" \
   --toolframe-output-directory build/installed-core
 ```
 
@@ -104,8 +103,8 @@ find-links directory, and output directory:
 ```sh
 .venv/bin/python scripts/smoke_wheel.py \
   --wheel dist/toolframe_testkit-0.1.2-py3-none-any.whl \
-  --fixture-wheel .local/wheelhouse/toolframe_testkit_fixture-0.1.0-py3-none-any.whl \
-  --find-links .local/wheelhouse \
+  --fixture-wheel build/wheelhouse/toolframe_testkit_fixture-0.1.0-py3-none-any.whl \
+  --find-links build/wheelhouse \
   --output build/wheel-smoke
 ```
 

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/docs/harness.md

@@ -14,9 +14,9 @@ from toolframe_testkit import ApplicationHarness
 with ApplicationHarness(
     "/path/to/toolframe-core",
     output_directory=Path("build/installed-core"),
-    find_links=[Path(".local/wheelhouse")],
+    find_links=[Path("build/wheelhouse")],
 ) as app:
-    app.install_plugin(".local/wheelhouse/my_plugin-0.1.0-py3-none-any.whl")
+    app.install_plugin("build/wheelhouse/my_plugin-0.1.0-py3-none-any.whl")
     app.wait_for_plugin("my-plugin")
     response = app.service_call(
         "my-plugin", "my.records", "list", {}, entrance="public"

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/docs/releasing.md

@@ -19,7 +19,7 @@ metadata and licenses, runs Ruff and package tests against an installed wheel,
 and installs each distribution into a separate fresh consumer environment.
 Optional database/service integrations require their documented fixtures.
 
-Publish `toolframe-sdk==0.3.0` first. The pytest extra is installed with `toolframe-testkit[pytest]`. The coordinated order and native CLI channels are documented in
+Publish `toolframe-sdk==0.4.0` first. The pytest extra is installed with `toolframe-testkit[pytest]`. The coordinated order and native CLI channels are documented in
 [Toolframe's release guide](https://github.com/toolframe/toolframe-core/blob/main/docs/releasing.md).
 
 ## Trusted Publishers
@@ -58,7 +58,7 @@ After PyPI publication, verify a clean installation:
 
 ```sh
 uv venv --python 3.14.7 build/consumer
-uv pip install --python build/consumer/bin/python 'toolframe-testkit==0.1.2'
+uv pip install --python build/consumer/bin/python 'toolframe-testkit==0.2.0'
 uv pip check --python build/consumer/bin/python
 ```
 

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/examples/installed_application.py

@@ -5,7 +5,7 @@ Example::
     python examples/installed_application.py \
       --core-command /path/to/toolframe-core \
       --wheelhouse .local/wheelhouse \
-      --storage-wheel /tmp/toolframe_storage_sqlite.whl \
+      --storage-wheel /tmp/toolframe_sql_sqlite.whl \
       --fixture-wheel /tmp/toolframe_testkit_fixture.whl \
       --output build/installed-application
 
@@ -21,7 +21,7 @@ from pathlib import Path
 
 from toolframe_testkit import ApplicationHarness
 
-_STORAGE_PLUGIN = "storage-sqlite"
+_STORAGE_PLUGIN = "sql-sqlite"
 _FIXTURE_PLUGIN = "fixture-records"
 _SERVICE = "fixture-records.records"
 

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "toolframe-testkit"
-version = "0.1.2"
+version = "0.2.0"
 description = "Public contract checks and installed-application tests for Toolframe developers"
 readme = "README.md"
 license = "Apache-2.0"
@@ -12,7 +12,7 @@ license-files = ["LICENSE"]
 authors = [{ name = "byfb", email = "62798989+byfb@users.noreply.github.com" }]
 requires-python = ">=3.14"
 dependencies = [
-  "toolframe-sdk==0.3.0", "httpx>=0.28,<1", "tomlkit>=0.13,<1", "psutil>=7,<9",
+  "toolframe-sdk==0.4.0", "httpx>=0.28,<1", "tomlkit>=0.13,<1", "psutil>=7,<9",
   "jsonschema>=4.23,<5", "pydantic>=2.12.5,<3",
 ]
 

toolframe_testkit-0.2.0/scripts/check_branch_name.py

@@ -0,0 +1,59 @@
+"""Validate a working branch using the repository's cchk.toml policy."""
+
+import argparse
+import re
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("branch", nargs="?", help="actual source branch in CI")
+    args = parser.parse_args()
+    root = Path(__file__).resolve().parent.parent
+    policy = tomllib.loads((root / "cchk.toml").read_text())["branch"]
+    branch = args.branch
+    if branch is None:
+        result = subprocess.run(
+            ["git", "symbolic-ref", "--quiet", "--short", "HEAD"],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode:
+            print(
+                "Pass the actual source branch when HEAD is detached.", file=sys.stderr
+            )
+            return 1
+        branch = result.stdout.strip()
+
+    if branch in policy["allow_branch_names"]:
+        return 0
+    prefix, separator, description = branch.partition("/")
+    pattern = (
+        r"[a-z0-9]+(?:[.-][a-z0-9]+)*"
+        if prefix == "release"
+        else r"[a-z0-9]+(?:-[a-z0-9]+)*"
+    )
+    if (
+        separator
+        and prefix in policy["allow_branch_types"]
+        and re.fullmatch(pattern, description)
+    ):
+        return 0
+
+    allowed = ", ".join(policy["allow_branch_types"])
+    print(
+        f"Invalid branch {branch!r}. Use <type>/<description> with type: {allowed}. "
+        "Use lowercase letters and digits separated by single hyphens; "
+        "release versions may also contain dots.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/scripts/smoke_wheel.py

@@ -66,7 +66,7 @@ def main():
         assert document["Requires-Python"] == ">=3.14"
         assert document["License-Expression"] == "Apache-2.0"
         requirements = document.get_all("Requires-Dist") or []
-        assert any(item.startswith("toolframe-sdk==0.3.0") for item in requirements)
+        assert any(item.startswith("toolframe-sdk==0.4.0") for item in requirements)
         assert not any(" @ " in item or "file:" in item for item in requirements)
         assert not any(
             "fixture_records/" in name or name.startswith("tests/") for name in names

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/src/toolframe_testkit/__init__.py

@@ -10,7 +10,7 @@ from .contracts import (
 )
 from .harness import ApplicationHarness, CLIResult, HarnessError, HarnessTimeout
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 __all__ = [
     "ApplicationHarness",
     "CLIResult",

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/tests/assets/service-plugin/pyproject.toml

@@ -9,7 +9,7 @@ description = "Small independently packaged Toolframe records plugin for testkit
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 requires-python = ">=3.14"
-dependencies = ["toolframe-sdk==0.3.0"]
+dependencies = ["toolframe-sdk==0.4.0"]
 
 [project.entry-points."toolframe.plugins"]
 fixture-records = "fixture_records.definition:plugin"

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/tests/assets/service-plugin/src/fixture_records/definition.py

@@ -87,7 +87,7 @@ plugin = PluginDefinition(
             "fixture-records.write": ScopeSpec(title="Append fixture records"),
         }
     ),
-    requires={"storage": Requirement(service="toolframe.storage.sql")},
+    requires={"sql": Requirement(service="toolframe.sql")},
     services={
         SERVICE: ServiceSpec(
             methods={

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/tests/assets/service-plugin/src/fixture_records/service.py

@@ -32,7 +32,7 @@ class Records(Plugin):
 
     async def append(self, body: object) -> dict:
         body = _validate_body(body)
-        storage = self.context.storage()
+        storage = self.context.sql()
         async with storage.transaction() as transaction:
             result = await transaction.execute_returning(
                 "INSERT INTO records(body) VALUES (?) RETURNING id",
@@ -62,7 +62,7 @@ class Records(Plugin):
 
     async def list_records(self, limit: object = 20) -> dict:
         limit = _validate_limit(limit)
-        records = await self.context.storage().query(
+        records = await self.context.sql().query(
             "SELECT id, body FROM records ORDER BY id DESC LIMIT ?",
             (limit,),
         )
@@ -90,5 +90,5 @@ class Records(Plugin):
         raise PluginError("method_not_found", f"Unknown method {service}/{method}")
 
     async def health(self) -> dict:
-        await self.context.storage().query("SELECT id FROM records LIMIT 1")
+        await self.context.sql().query("SELECT id FROM records LIMIT 1")
         return {"runtime": "ready", "business": "ready"}

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/tests/test_installed_core.py

@@ -17,7 +17,7 @@ pytestmark = pytest.mark.installed_core
 
 _STORAGE_WHEEL_ENV = "TOOLFRAME_TESTKIT_STORAGE_WHEEL"
 _FIXTURE_WHEEL_ENV = "TOOLFRAME_TESTKIT_FIXTURE_WHEEL"
-_STORAGE_PLUGIN = "storage-sqlite"
+_STORAGE_PLUGIN = "sql-sqlite"
 _FIXTURE_PLUGIN = "fixture-records"
 _SERVICE = "fixture-records.records"
 

{toolframe_testkit-0.1.2 → toolframe_testkit-0.2.0}/uv.lock

@@ -448,7 +448,7 @@ wheels = [
 
 [[package]]
 name = "toolframe-sdk"
-version = "0.3.0"
+version = "0.4.0"
 source = { editable = "../toolframe-sdk" }
 dependencies = [
     { name = "jsonschema" },
@@ -475,7 +475,7 @@ dev = [
 
 [[package]]
 name = "toolframe-testkit"
-version = "0.1.2"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },