forge-template 0.3.1__tar.gz

forge_template-0.3.1/.gitattributes

@@ -0,0 +1,12 @@
+# Normalise to LF in the repository. Without this, Windows checkouts get CRLF
+# and a fresh clone's checked-out template/*.jinja files would render CRLF
+# into every scaffolded project.
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.whl binary

forge_template-0.3.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Report something that isn't working as expected
+labels: ["type:bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: >
+        Include the answers (or which combo, if this is about
+        `tests/test_combos.py`) that reproduce it.
+      placeholder: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+
+  - type: input
+    id: template-version
+    attributes:
+      label: Template version
+      description: The tag `copier` scaffolded from, or `main` at a commit SHA
+      placeholder: "e.g. v0.1.1"
+    validations:
+      required: true
+
+  - type: input
+    id: copier-version
+    attributes:
+      label: Copier version
+      placeholder: "e.g. 9.4.1 (uv run copier --version)"
+    validations:
+      required: false

forge_template-0.3.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: create-forge CLI issue
+    url: https://github.com/Sandsy09/create-forge/issues/new/choose
+    about: Report a problem with the `create-forge` CLI itself, not this template.

forge_template-0.3.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Feature request
+description: Suggest an idea or enhancement
+labels: ["type:feature"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: What are you trying to do that isn't possible or easy today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like to happen?
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

forge_template-0.3.1/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels: ["type:chore", "area:ci"]
+    commit-message:
+      prefix: ci

forge_template-0.3.1/.github/labels.toml

@@ -0,0 +1,100 @@
+# Shared GitHub label taxonomy for create-forge and forge-template.
+#
+# This is the source of truth -- applied with `uv run poe labels:sync`
+# (scripts/labels.py), which also accepts `--repo OWNER/NAME` so the same
+# manifest drives forge-template. See CONTRIBUTING.md's Labels section.
+#
+# Group labels are namespaced "<group>:<label>" (e.g. "area:cli"). Entries
+# under [unprefixed] keep GitHub's stock names -- "good first issue" and
+# "help wanted" are special-cased by GitHub's own issue-discovery UI, so
+# renaming them would cost real functionality for no benefit.
+#
+# Most `type:` values mirror the Conventional Commits prefixes both repos
+# already enforce via their commit-msg hook. `type:epic` and `type:decision`
+# classify roadmap planning work that does not map to a single commit.
+
+[groups.area]
+description = "Which part of the system an issue touches."
+family = "blue"
+
+[groups.area.labels]
+cli = { color = "0a3069", description = "The Typer commands and their prompts" }
+registry = { color = "0550ae", description = "templates.toml and the models that validate it" }
+copier = { color = "0969da", description = "The Copier integration and copier.yml surface" }
+template = { color = "218bff", description = "forge-template's scaffolded files and tasks" }
+ci = { color = "54aeff", description = "GitHub Actions workflows and the checks they run" }
+tests = { color = "80ccff", description = "The test suites and fixtures themselves" }
+docs = { color = "b6e3ff", description = "README, CONTRIBUTING, ADRs, and other documentation" }
+packaging = { color = "cae8ff", description = "pyproject.toml, dependencies, and the built wheel" }
+release = { color = "ddf4ff", description = "Tagging, changelog generation, and the release workflow" }
+
+[groups.type]
+description = "What kind of work an issue or PR represents."
+family = "purple"
+
+[groups.type.labels]
+epic = { color = "2f0f5f", description = "A roadmap stage grouping related child issues" }
+decision = { color = "5526a5", description = "An architectural or product decision is required" }
+bug = { color = "3e1f79", description = "Something isn't working" }
+feature = { color = "6639ba", description = "New capability or request" }
+refactor = { color = "8250df", description = "Structural change with no behaviour change" }
+perf = { color = "a475f9", description = "Performance improvement" }
+docs = { color = "c297ff", description = "Documentation-only change" }
+test = { color = "d8b9ff", description = "Test-only change" }
+chore = { color = "ecd8ff", description = "Maintenance with no user-facing effect" }
+
+[groups.priority]
+description = "How urgently an issue should be picked up."
+family = "red"
+
+[groups.priority.labels]
+critical = { color = "82071e", description = "Drop everything" }
+high = { color = "cf222e", description = "Should be next" }
+medium = { color = "ff8182", description = "Normal priority" }
+low = { color = "ffcecb", description = "Nice to have" }
+
+[groups.size]
+description = "Rough estimate of how much work an issue is."
+family = "green"
+
+[groups.size.labels]
+xs = { color = "dafbe1", description = "Trivial -- minutes" }
+s = { color = "aceebb", description = "Small -- a sitting" }
+m = { color = "6fdd8b", description = "Medium -- a day or two" }
+l = { color = "2da44e", description = "Large -- the better part of a week" }
+xl = { color = "116329", description = "Extra large -- consider breaking it up" }
+
+[groups.status]
+description = "Where an issue stands, independent of priority or size."
+family = "slate"
+
+[groups.status.labels]
+blocked = { color = "24292f", description = "Waiting on something outside this issue" }
+needs-decision = { color = "57606a", description = "Blocked on a choice only a maintainer can make" }
+needs-info = { color = "6e7781", description = "Waiting on more information before work can start" }
+in-progress = { color = "8c959f", description = "Actively being worked on" }
+deferred = { color = "afb8c1", description = "Confirmed out of scope for now, not forgotten" }
+
+[groups.roadmap]
+description = "Which Forge Foundation roadmap stage owns the work."
+family = "orange"
+
+[groups.roadmap.labels]
+"00" = { color = "fff8c5", description = "Forge roadmap Stage 00 — Governance and Principles" }
+"01" = { color = "fae17d", description = "Forge roadmap Stage 01 — Python Core" }
+"02" = { color = "f7c843", description = "Forge roadmap Stage 02 — Developer Experience" }
+"03" = { color = "f2b134", description = "Forge roadmap Stage 03 — Quality and CI" }
+"04" = { color = "ed9b2d", description = "Forge roadmap Stage 04 — Runtime and Configuration" }
+"05" = { color = "e78626", description = "Forge roadmap Stage 05 — Security and Supply Chain" }
+"06" = { color = "df7020", description = "Forge roadmap Stage 06 — Extension and Composition" }
+"07" = { color = "d45d1a", description = "Forge roadmap Stage 07 — Forge CLI Integration" }
+"08" = { color = "bd4914", description = "Forge roadmap Stage 08 — Reference Archetype Validation" }
+"09" = { color = "9f3610", description = "Forge roadmap Stage 09 — Blueprint Compatibility" }
+
+# Repository-wide metadata that is clearer without a namespace. GitHub
+# special-cases `good first issue` and `help wanted` in its discovery UI.
+[unprefixed]
+"good first issue" = { color = "7057ff", description = "Good for newcomers" }
+"help wanted" = { color = "008672", description = "Extra attention is needed" }
+"cross-repo" = { color = "1f6feb", description = "Coordinates work across create-forge and forge-template" }
+"breaking-change" = { color = "b60205", description = "May require an incompatible migration or coordinated release" }

forge_template-0.3.1/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+
+<!-- What does this change do, and why? -->
+
+## Checklist
+
+- [ ] `uv run poe check` passes locally
+- [ ] `uv run poe combos` passes, if this touches `template/` or `copier.yml`
+- [ ] `uv run poe update` passes, if this edits a file that already exists in
+      released projects
+- [ ] An ADR is added under `docs/adr/`, if this makes a real architectural call
+- [ ] A `_migrations` block is added, if any `template/` path was renamed or
+      deleted (see CLAUDE.md's invariant 3)
+- [ ] Any conditional file I touched still ends in a real trailing newline
+      (invariant 1)
+- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)

forge_template-0.3.1/.github/workflows/release.yml

@@ -0,0 +1,137 @@
+name: Release template
+
+# Tags are how Copier resolves "latest version" and how engine clients resolve
+# package compatibility. pyproject.toml is the one version source: bump it in
+# a reviewed PR, then run this workflow to create the matching tag and release.
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Print the tag without creating it
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+
+env:
+  UV_VERSION: "0.12.0"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Read and validate version
+        id: version
+        shell: bash
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::project.version must be a final SemVer release, found: $version"
+            exit 1
+          fi
+
+          next="v$version"
+          latest=$(git tag -l 'v*' --sort=-v:refname | head -1)
+          if git rev-parse --verify --quiet "refs/tags/$next" >/dev/null; then
+            echo "::error::tag already exists: $next"
+            exit 1
+          fi
+          if [ -n "$latest" ] && [ "$(printf '%s\n%s\n' "$latest" "$next" | sort -V | tail -1)" != "$next" ]; then
+            echo "::error::project version $next is not newer than $latest"
+            exit 1
+          fi
+
+          echo "latest=${latest:-none}" >> "$GITHUB_OUTPUT"
+          echo "next=$next" >> "$GITHUB_OUTPUT"
+          echo "### ${latest:-none} → $next" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Changes since last release
+        id: notes
+        run: |
+          latest="${{ steps.version.outputs.latest }}"
+          {
+            echo "notes<<EOF"
+            if [ "$latest" = "none" ]; then
+              echo "Initial release."
+            else
+              git log "${latest}..HEAD" --pretty='- %s' --no-merges
+            fi
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Warn on breaking template changes
+        run: |
+          latest="${{ steps.version.outputs.latest }}"
+          [ "$latest" = "none" ] && exit 0
+          moved=$(git diff --name-status "$latest..HEAD" -- template/ \
+                  | grep -E '^(R|D)' || true)
+          if [ -n "$moved" ] && ! grep -q '_migrations' copier.yml; then
+            echo "::warning::Template files moved or deleted with no _migrations block:"
+            echo "$moved"
+          fi
+
+      - name: Create tag
+        if: ${{ !inputs.dry_run }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "${{ steps.version.outputs.next }}" \
+            -m "Release ${{ steps.version.outputs.next }}"
+          git push origin "${{ steps.version.outputs.next }}"
+
+      - name: GitHub release
+        if: ${{ !inputs.dry_run }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ steps.version.outputs.next }}" \
+            --title "${{ steps.version.outputs.next }}" \
+            --notes "${{ steps.notes.outputs.notes }}
+
+          ---
+          Existing projects can pull this in with \`uvx copier update --trust\`."
+
+  # ---------------------------------------------------------------------------
+  # Publishes the public engine package built from the same commit the tag
+  # above points to. Uses PyPI Trusted Publishing (OIDC) -- no stored token.
+  # ADR 0036: only the public engine facade and content trees ship in this
+  # wheel; scripts/check_wheel.py (already required by CI's `wheel` job)
+  # re-verifies that here as a release-time safety net.
+  # ---------------------------------------------------------------------------
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: release
+    if: ${{ !inputs.dry_run }}
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/forge-template
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Check wheel contents
+        run: uv run poe check:wheel
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

forge_template-0.3.1/.github/workflows/test-template.yml

@@ -0,0 +1,211 @@
+name: Test template
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  # Catches upstream breakage (new ruff rules, uv releases) before users do.
+  schedule:
+    - cron: "0 6 * * 1"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  UV_VERSION: "0.12.0"
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Cheap checks on the template repo itself.
+  # ---------------------------------------------------------------------------
+  lint:
+    name: Lint template
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      # Same gate as `uv run pre-commit run --all-files` locally: ruff,
+      # shellcheck, and the whitespace/EOF hooks that guard invariant 1.
+      - name: Pre-commit
+        run: uv run pre-commit run --all-files --show-diff-on-failure
+
+      # copier.yml layout, computed-value defaults, the versioning /
+      # versioning_resolved indirection, question <-> template/** usage, and
+      # the docs/adr/ set -- see src/forge_template/{schema,adr}.py.
+      - name: Schema and unit tests
+        run: uv run poe check
+
+  # ---------------------------------------------------------------------------
+  # Scaffold every combination, then run the checks the generated CI runs.
+  # tests/test_combos.py is the single definition of every assertion here --
+  # see tests/conftest.py's --from-git option and _git_identity fixture (no
+  # manual `git config` step needed; the fixture supplies one when the runner
+  # has none, closing the bug class documented in CLAUDE.md's "Validation").
+  # ---------------------------------------------------------------------------
+  scaffold:
+    name: ${{ matrix.name }}
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: uv_build + static
+            combo: c1-uvbuild-static
+          - name: hatchling + static
+            combo: c2-hatch-static
+          - name: hatchling + vcs
+            combo: c3-hatch-vcs
+          - name: kitchen sink (all conditionals on)
+            combo: c4-kitchen-sink
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          # Copier needs tag history to record _commit in the answers file.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Scaffold and verify -- ${{ matrix.combo }}
+        run: uv run pytest -m combos -k ${{ matrix.combo }} --from-git -v
+
+  # ---------------------------------------------------------------------------
+  # Windows smoke test — path separators, line endings, missing Unix tools.
+  # ---------------------------------------------------------------------------
+  windows:
+    name: Windows smoke
+    runs-on: windows-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Scaffold and verify -- c1-uvbuild-static
+        run: uv run pytest -m combos -k c1-uvbuild-static --from-git -v
+
+  # ---------------------------------------------------------------------------
+  # Real uv build/install/import proof for the production Library and CLI
+  # archetypes -- tests/test_library_build.py, tests/test_cli_build.py.
+  # ---------------------------------------------------------------------------
+  archetype:
+    name: Archetype builds
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Build every production archetype
+        run: uv run poe archetype
+
+  # ---------------------------------------------------------------------------
+  # copier update from the last release to HEAD must not explode, and local
+  # edits survive a merge. tests/test_update.py's two scenarios each skip
+  # themselves (not fail) when no tag exists yet -- the very first run.
+  # ---------------------------------------------------------------------------
+  update-compat:
+    name: copier update compatibility
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: copier update scenarios
+        run: uv run pytest -m update -v
+
+  # ---------------------------------------------------------------------------
+  # Verifies the built wheel ships the public engine facade and content
+  # trees but excludes this repo's own CI tooling (adr.py, render.py,
+  # schema.py, github_actions.py) -- see ADR 0036 and scripts/check_wheel.py.
+  # ---------------------------------------------------------------------------
+  wheel:
+    name: Wheel contents
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Check wheel
+        run: uv run poe check:wheel
+
+  # ---------------------------------------------------------------------------
+  # Single required status check for branch protection.
+  # ---------------------------------------------------------------------------
+  all-green:
+    name: All checks passed
+    runs-on: ubuntu-latest
+    needs: [lint, scaffold, windows, archetype, update-compat, wheel]
+    if: always()
+    steps:
+      - name: Verify
+        run: |
+          if echo "${{ join(needs.*.result, ',') }}" | grep -qE 'failure|cancelled'; then
+            echo "::error::One or more jobs failed"; exit 1
+          fi
+          echo "All jobs passed."