@opengroundplan/core 0.1.1

package/templates/layers/cache-redis/files/tests/test_cache_redis.py

@@ -0,0 +1,105 @@
+"""Contract tests for the cache seam.
+
+Driven with ``asyncio.run`` so they need only pytest — no async plugin, and no Redis: the
+fallback store implements the same contract the Redis store does.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+
+import pytest
+
+from {{ solutionName | snake }}.cache.api import (
+    MemoryCacheStore,
+    build_key,
+    load_cache_settings,
+)
+
+NAMESPACE = "user"
+
+
+def _store(**overrides: object) -> MemoryCacheStore:
+    settings = replace(load_cache_settings(), **overrides)
+    return MemoryCacheStore(settings)
+
+
+def test_build_key_joins_prefix_namespace_and_id() -> None:
+    assert build_key("app", NAMESPACE, "42") == "app:user:42"
+
+
+@pytest.mark.parametrize("bad", ["with space", "glob*", "brack[et]"])
+def test_build_key_rejects_unsafe_segments(bad: str) -> None:
+    with pytest.raises(ValueError):
+        build_key("app", NAMESPACE, bad)
+
+
+def test_get_returns_none_on_miss() -> None:
+    store = _store()
+    assert asyncio.run(store.get(NAMESPACE, "missing")) is None
+
+
+def test_set_then_get_roundtrips_json() -> None:
+    store = _store()
+
+    async def scenario() -> object:
+        await store.set(NAMESPACE, "1", {"name": "Ada", "tags": [1, 2]})
+        return await store.get(NAMESPACE, "1")
+
+    assert asyncio.run(scenario()) == {"name": "Ada", "tags": [1, 2]}
+
+
+def test_expired_entry_reads_as_a_miss() -> None:
+    store = _store()
+
+    async def scenario() -> object:
+        await store.set(NAMESPACE, "1", "value", ttl_seconds=1)
+        # Expiry is compared against a monotonic clock; rewind the entry instead of sleeping.
+        entry = next(iter(store._entries.values()))
+        entry.expires_at = 0.0
+        return await store.get(NAMESPACE, "1")
+
+    assert asyncio.run(scenario()) is None
+
+
+def test_get_or_set_loads_once() -> None:
+    store = _store()
+    calls = 0
+
+    async def load() -> str:
+        nonlocal calls
+        calls += 1
+        return "loaded"
+
+    async def scenario() -> tuple[str, str]:
+        first = await store.get_or_set(NAMESPACE, "1", load)
+        second = await store.get_or_set(NAMESPACE, "1", load)
+        return first, second
+
+    assert asyncio.run(scenario()) == ("loaded", "loaded")
+    assert calls == 1
+
+
+def test_invalidate_namespace_drops_only_that_namespace() -> None:
+    store = _store()
+
+    async def scenario() -> tuple[int, object]:
+        await store.set(NAMESPACE, "1", "a")
+        await store.set(NAMESPACE, "2", "b")
+        await store.set("order", "1", "c")
+        removed = await store.invalidate_namespace(NAMESPACE)
+        return removed, await store.get("order", "1")
+
+    assert asyncio.run(scenario()) == (2, "c")
+
+
+def test_memory_store_is_bounded() -> None:
+    store = _store(memory_max_entries=2)
+
+    async def scenario() -> object:
+        for index in range(3):
+            await store.set(NAMESPACE, str(index), index)
+        return await store.get(NAMESPACE, "0")
+
+    assert asyncio.run(scenario()) is None

package/templates/layers/ci-github-actions/blueprint.yaml

@@ -0,0 +1,174 @@
+id: ci-github-actions
+kind: layer
+name: GitHub Actions CI
+description: >-
+  Continuous integration on GitHub Actions: lint, typecheck, build, and test as
+  separate jobs, a version/OS matrix, dependency caching, a single aggregating
+  gate job to protect the default branch with, and Dependabot for the actions
+  themselves. Every command lives in the workflow's `env` block, so a change
+  lands in exactly one place.
+
+tags:
+  - ci
+  - github-actions
+  - build
+  - test
+  - lint
+  - typecheck
+  - matrix
+  - caching
+  - automation
+
+# Nothing to depend on: the workflows drive the toolchain the base already ships
+# (package.json scripts, pyproject, .slnx, go.mod) and read nothing from another layer.
+requires: []
+
+# Must name blueprints that exist — the loader rejects dangling ids
+# (loader.assertReferencesResolve). A future ci-gitlab / ci-azure-pipelines declares the
+# conflict from its own side; conflicts are symmetric at resolve time anyway.
+conflicts: []
+
+# Capability names other layers and docs can key off instead of naming this layer.
+provides:
+  - ci
+  - ci-pipeline
+  - build-pipeline
+  - test-pipeline
+  - lint-pipeline
+  - typecheck-pipeline
+  - dependency-caching
+  - required-checks
+  - github-actions
+
+# CI is an infrastructure concern; it does not care how the source tree is organized.
+supportsArchitectures: []
+
+variables:
+  # ── every stack ─────────────────────────────────────────────────────────────
+  - name: ciDefaultBranch
+    prompt: Branch that push builds and pull-request targets are gated on
+    type: string
+    default: main
+    required: true
+
+  - name: ciRunner
+    prompt: Runner for the single-runner jobs (lint, typecheck, gate)
+    type: select
+    default: ubuntu-latest
+    required: true
+    choices:
+      - { value: ubuntu-latest, label: ubuntu-latest }
+      - { value: ubuntu-24.04, label: 'ubuntu-24.04 (pinned)' }
+      - { value: windows-latest, label: windows-latest }
+      - { value: macos-latest, label: macos-latest }
+
+  - name: ciMatrixOs
+    prompt: 'Runner matrix for build and test, as a YAML list (e.g. ["ubuntu-latest", "windows-latest"])'
+    type: string
+    default: '["ubuntu-latest"]'
+    required: true
+
+  - name: ciTimeoutMinutes
+    prompt: Per-job timeout in minutes
+    type: number
+    default: 15
+    required: true
+
+  # ── node-family (typescript / node / polyglot) ──────────────────────────────
+  # Same name as the bases declare, so a Node interview asks it once.
+  - name: packageManager
+    prompt: Package manager CI installs with
+    type: select
+    default: pnpm
+    required: true
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+    choices:
+      - { value: pnpm, label: pnpm }
+      - { value: npm, label: npm }
+      - { value: yarn, label: Yarn }
+      - { value: bun, label: Bun }
+
+  - name: ciNodeVersion
+    prompt: Node version used by the single-runner jobs
+    type: string
+    default: '24'
+    required: true
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+
+  - name: ciNodeVersions
+    prompt: 'Node versions to build and test against, as a YAML list'
+    type: string
+    default: '[22, 24]'
+    required: true
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - name: ciPythonVersion
+    prompt: Python version used by the single-runner jobs
+    type: string
+    default: '3.13'
+    required: true
+    when: "stack == 'python'"
+
+  - name: ciPythonVersions
+    prompt: 'Python versions to test against, as a YAML list — all must satisfy requires-python'
+    type: string
+    default: '["3.13"]'
+    required: true
+    when: "stack == 'python'"
+
+files:
+  # ── every supported stack ───────────────────────────────────────────────────
+  # Keeps the action versions pinned in the workflows from going stale. Gated on the
+  # stacks that actually receive a workflow, so an unsupported base gets nothing.
+  # security-supply-chain ships a superset of this file (language ecosystem + cooldown), so
+  # yield to it when both layers are selected. Declared here as well as there because which
+  # of the two applies second depends on selection order.
+  - from: files/.github/dependabot.yml
+    to: .
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot' || stack == 'python' || stack == 'dotnet' || stack == 'go'"
+    onConflict: skip
+  - from: files/docs/ci-github-actions.md
+    to: .
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot' || stack == 'python' || stack == 'dotnet' || stack == 'go'"
+
+  # ── typescript / node / polyglot ────────────────────────────────────────────
+  # polyglot is the Turborepo base: same toolchain, and the script lookup falls through
+  # to `check-types` when a repo names the task that way.
+  - from: files/.github/workflows/ci-node.yml
+    to: .
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+  - from: files/.github/actions/node-setup/action.yml
+    to: .
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+  - from: files/.github/scripts/run-package-script.sh
+    to: .
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - from: files/.github/workflows/ci-python.yml
+    to: .
+    when: "stack == 'python'"
+  - from: files/.github/actions/python-setup/action.yml
+    to: .
+    when: "stack == 'python'"
+
+  # ── dotnet ──────────────────────────────────────────────────────────────────
+  - from: files/.github/workflows/ci-dotnet.yml
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/.github/actions/dotnet-setup/action.yml
+    to: .
+    when: "stack == 'dotnet'"
+
+  # ── go ──────────────────────────────────────────────────────────────────────
+  - from: files/.github/workflows/ci-go.yml
+    to: .
+    when: "stack == 'go'"
+  - from: files/.github/actions/go-setup/action.yml
+    to: .
+    when: "stack == 'go'"
+
+# Nothing to install or mutate: the workflows only run on GitHub. Branch protection is a
+# remote change, so docs/ci-github-actions.md carries the command instead of running it.
+postApply: []

package/templates/layers/ci-github-actions/files/.github/actions/dotnet-setup/action.yml

@@ -0,0 +1,25 @@
+name: .NET setup
+description: Install the SDK pinned in global.json, restore NuGet from a cache, and restore the solution.
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-dotnet@v6
+      with:
+        global-json-file: global.json
+
+    # A workspace-local package folder is the same path on every runner OS,
+    # which keeps the cache step below portable.
+    - name: Point NuGet at a cacheable folder
+      shell: bash
+      run: echo "NUGET_PACKAGES=$GITHUB_WORKSPACE/.nuget/packages" >> "$GITHUB_ENV"
+
+    - uses: actions/cache@v6
+      with:
+        path: .nuget/packages
+        key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj', '**/Directory.Packages.props', '**/global.json') }}
+        restore-keys: ${{ runner.os }}-nuget-
+
+    - name: Restore
+      shell: bash
+      run: dotnet restore

package/templates/layers/ci-github-actions/files/.github/actions/go-setup/action.yml

@@ -0,0 +1,30 @@
+name: Go setup
+description: Install the toolchain pinned in go.mod and restore the module and build caches.
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-go@v7
+      with:
+        go-version-file: go.mod
+        # setup-go's own cache errors out when go.sum is absent; handled below instead.
+        cache: false
+
+    - name: Resolve the Go cache directories
+      id: paths
+      shell: bash
+      run: |
+        echo "build=$(go env GOCACHE)" >> "$GITHUB_OUTPUT"
+        echo "mod=$(go env GOMODCACHE)" >> "$GITHUB_OUTPUT"
+
+    - uses: actions/cache@v6
+      with:
+        path: |
+          ${{ steps.paths.outputs.build }}
+          ${{ steps.paths.outputs.mod }}
+        key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum', '**/go.mod') }}
+        restore-keys: ${{ runner.os }}-go-
+
+    - name: Download modules
+      shell: bash
+      run: go mod download

package/templates/layers/ci-github-actions/files/.github/actions/node-setup/action.yml

@@ -0,0 +1,58 @@
+name: Node setup
+description: Install Node, restore the package-manager cache, and install dependencies.
+
+# Everything arrives as an input rather than being read from the caller's `env`:
+# the env context is not reliably visible inside composite actions.
+inputs:
+  node-version:
+    description: Node.js version to install.
+    required: true
+  package-manager:
+    description: pnpm, npm, yarn, or bun.
+    required: true
+  install-command:
+    description: Command that installs dependencies.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    # Corepack ships the pnpm/yarn version pinned by package.json#packageManager.
+    - name: Enable Corepack
+      if: inputs.package-manager == 'pnpm' || inputs.package-manager == 'yarn'
+      shell: bash
+      run: corepack enable
+
+    - name: Install Bun
+      if: inputs.package-manager == 'bun'
+      uses: oven-sh/setup-bun@v2
+
+    - uses: actions/setup-node@v7
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    - name: Resolve the package-manager store
+      id: store
+      shell: bash
+      env:
+        PM: ${{ inputs.package-manager }}
+      run: |
+        case "$PM" in
+          pnpm) dir=$(pnpm store path --silent) ;;
+          yarn) dir=$(yarn config get cacheFolder 2>/dev/null || yarn cache dir) ;;
+          bun)  dir="$HOME/.bun/install/cache" ;;
+          *)    dir=$(npm config get cache) ;;
+        esac
+        echo "dir=$dir" >> "$GITHUB_OUTPUT"
+
+    # Keyed on every lockfile shape so the cache stays correct if the package
+    # manager changes; a repo with no lockfile still gets a warm restore-key hit.
+    - uses: actions/cache@v6
+      with:
+        path: ${{ steps.store.outputs.dir }}
+        key: ${{ runner.os }}-${{ inputs.package-manager }}-${{ hashFiles('**/pnpm-lock.yaml', '**/package-lock.json', '**/yarn.lock', '**/bun.lock', '**/bun.lockb') }}
+        restore-keys: ${{ runner.os }}-${{ inputs.package-manager }}-
+
+    - name: Install dependencies
+      shell: bash
+      run: ${{ inputs.install-command }}

package/templates/layers/ci-github-actions/files/.github/actions/python-setup/action.yml

@@ -0,0 +1,23 @@
+name: Python setup
+description: Install uv and the requested Python, restore the uv cache, and sync dependencies.
+
+inputs:
+  python-version:
+    description: Python version to install.
+    required: true
+  install-command:
+    description: Command that installs project dependencies.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    # setup-uv caches ~/.cache/uv itself, keyed on the lockfile — no extra cache step.
+    - uses: astral-sh/setup-uv@v8
+      with:
+        python-version: ${{ inputs.python-version }}
+        enable-cache: true
+
+    - name: Install dependencies
+      shell: bash
+      run: ${{ inputs.install-command }}

package/templates/layers/ci-github-actions/files/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  # The workflows pin action majors; without this they quietly rot.
+  # Add your language ecosystem (npm / uv / nuget / gomod) here when you want
+  # dependency PRs for the application itself too.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      actions:
+        patterns: ['*']

package/templates/layers/ci-github-actions/files/.github/scripts/run-package-script.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Run the first of the given package.json scripts that exists, or skip cleanly.
+# Bases and layers do not all agree on script names (typecheck vs check-types) and
+# none of them ship a test script until you write one — neither should fail CI.
+set -euo pipefail
+
+for script in "$@"; do
+  if node -e "process.exit(require('./package.json').scripts?.['$script'] ? 0 : 1)"; then
+    exec "${PACKAGE_MANAGER:-npm}" run "$script"
+  fi
+done
+
+echo "::notice::no $* script in package.json — skipped"

package/templates/layers/ci-github-actions/files/.github/workflows/ci-dotnet.yml

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches: [{{ ciDefaultBranch }}]
+  pull_request:
+    branches: [{{ ciDefaultBranch }}]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# The only place commands are written. Jobs read from here.
+env:
+  BUILD_COMMAND: dotnet build --no-restore --configuration Release
+  TEST_COMMAND: dotnet test --no-restore --configuration Release
+  FORMAT_CHECK_COMMAND: dotnet format --verify-no-changes --no-restore
+  DOTNET_NOLOGO: 'true'
+  DOTNET_CLI_TELEMETRY_OPTOUT: 'true'
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # There is no separate typecheck job: Directory.Build.props turns warnings into
+  # errors and enforces code style in the build, so `build` is the type gate.
+  lint:
+    name: Lint
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/dotnet-setup
+      - name: Verify formatting and code style
+        run: $FORMAT_CHECK_COMMAND
+
+  build:
+    name: Build (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    strategy:
+      # One red cell should not hide the state of the others.
+      fail-fast: false
+      matrix:
+        os: {{ ciMatrixOs }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/dotnet-setup
+      - run: $BUILD_COMMAND
+
+  test:
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: {{ ciMatrixOs }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/dotnet-setup
+      # Exits 0 when the solution has no test project yet, so this stays green
+      # until the first test project is added.
+      - run: $TEST_COMMAND
+
+  # The one check to mark required in branch protection: matrix cells come and go
+  # as the runner list changes, but this job's name never does.
+  gate:
+    name: CI gate
+    if: always()
+    needs: [lint, build, test]
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - name: Verify every required job succeeded
+        run: |
+          if ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}; then
+            echo "::error::a required job did not succeed"
+            exit 1
+          fi

package/templates/layers/ci-github-actions/files/.github/workflows/ci-go.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [{{ ciDefaultBranch }}]
+  pull_request:
+    branches: [{{ ciDefaultBranch }}]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# The only place commands are written. Jobs read from here.
+env:
+  BUILD_COMMAND: go build ./...
+  TEST_COMMAND: go test -race -coverprofile=coverage.out ./...
+  VET_COMMAND: go vet ./...
+  # gofmt reports offending files on stdout and still exits 0, so the step checks output.
+  FORMAT_LIST_COMMAND: gofmt -l .
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # There is no separate typecheck job: the Go compiler is the type checker, and
+  # `go vet` here plus `build` below cover it.
+  lint:
+    name: Lint
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/go-setup
+      - name: gofmt
+        run: |
+          unformatted=$($FORMAT_LIST_COMMAND)
+          if [ -n "$unformatted" ]; then
+            echo "::error::gofmt would rewrite: $unformatted"
+            exit 1
+          fi
+      - name: go vet
+        run: $VET_COMMAND
+
+  build:
+    name: Build (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    strategy:
+      # One red cell should not hide the state of the others.
+      fail-fast: false
+      matrix:
+        os: {{ ciMatrixOs }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/go-setup
+      - run: $BUILD_COMMAND
+
+  test:
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: {{ ciMatrixOs }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/go-setup
+      # Exits 0 with "no test files" until the first _test.go lands.
+      - run: $TEST_COMMAND
+
+  # The one check to mark required in branch protection: matrix cells come and go
+  # as the runner list changes, but this job's name never does.
+  gate:
+    name: CI gate
+    if: always()
+    needs: [lint, build, test]
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - name: Verify every required job succeeded
+        run: |
+          if ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}; then
+            echo "::error::a required job did not succeed"
+            exit 1
+          fi