diff --git a/.coderabbit.yaml b/.coderabbit.yaml new file mode 100644 index 0000000..37f350c --- /dev/null +++ b/.coderabbit.yaml @@ -0,0 +1,15 @@ +# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json +# +# Shared CodeRabbit settings for every application made from application-template. +# The template owns this file and template-sync keeps it current, so a change here +# reaches every application. `inheritance: true` layers it over the organization's +# CodeRabbit settings. To diverge, list `.coderabbit.yaml` in your +# `.templatesyncignore` and own your copy. +inheritance: true +reviews: + # A review finding is a comment to fix or refute, not a failed status check: + # CI - Required Checks is the merge gate. + fail_commit_status: false + pre_merge_checks: + docstrings: + mode: warning diff --git a/.github/codeql/codeql-config.yml b/.github/codeql/codeql-config.yml new file mode 100644 index 0000000..78269a0 --- /dev/null +++ b/.github/codeql/codeql-config.yml @@ -0,0 +1,16 @@ +# What CodeQL analyses in this application. This file is yours: template-sync never +# overwrites it, while .github/workflows/codeql.yaml, which reads it, stays shared. +# Reference: https://docs.github.com/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning +name: CodeQL configuration + +# security-extended adds lower-precision security queries to the default suite. +queries: + - uses: security-extended + +# Generated and vendored output is not your code. +paths-ignore: + - "**/node_modules" + - "**/.svelte-kit" + - "**/build" + - "**/bin" + - "**/obj" diff --git a/.github/mega-linter.base.yml b/.github/mega-linter.base.yml new file mode 100644 index 0000000..a13c3fa --- /dev/null +++ b/.github/mega-linter.base.yml @@ -0,0 +1,63 @@ +# Shared MegaLinter settings for every application made from application-template. +# The template owns this file and template-sync keeps it current. Your own settings +# go in .mega-linter.yml, which extends this file and wins wherever they differ. +# +# MegaLinter checks what every repository shares: workflows, shell scripts, +# Dockerfiles, Markdown, YAML and JSON, Kubernetes manifests, and leaked secrets. +# Each stack's own CI lints its language (golangci-lint, ESLint and svelte-check, +# the .NET analyzers), so MegaLinter does not lint those again. +FLAVOR_SUGGESTIONS: false +IGNORE_GITIGNORED_FILES: true +SHOW_ELAPSED_TIME: true +# Linter configuration files (.markdownlint.json, .yamllint.yml, ...) live at the root. +LINTER_RULES_PATH: . +# Generated lockfiles are not hand-written and are not linted. +FILTER_REGEX_EXCLUDE: (package-lock\.json|go\.sum) +EXCLUDED_DIRECTORIES: + - .git + - megalinter-reports + - node_modules + - .svelte-kit + - build + - bin + - obj +DISABLE: + # Languages the stack's CI owns. + - GO + - JAVASCRIPT + - TYPESCRIPT + - TSX + - JSX + # Spelling and copy-paste detection are opt-in: add them back in .mega-linter.yml. + - COPYPASTE + - SPELL +DISABLE_LINTERS: + # The organization's required zizmor and dependency-review workflows cover these. + - ACTION_ZIZMOR + - REPOSITORY_GRYPE + - REPOSITORY_OSV_SCANNER + # Scripts run through `sh`, so they need no executable bit; their formatting is the + # owner's choice, and shellcheck still checks that they are correct. + - BASH_EXEC + - BASH_SHFMT + # Reformats tables only; markdownlint checks the Markdown itself. + - MARKDOWN_MARKDOWN_TABLE_FORMATTER + # deploy/ follows the platform's conventions (namespace set at reconcile time, UID 1000, + # no CPU limit, the image digest pinned at release), which the platform's own admission + # policies enforce. These generic policy scanners contradict them on every manifest. + - REPOSITORY_CHECKOV + - KUBERNETES_KUBESCAPE + # A Jinja/Django template linter; plain HTML is checked by htmlhint. + - HTML_DJLINT +# Kubernetes manifests use custom resources (CloudNativePG, External Secrets, Gateway +# API) whose schemas are not bundled; core kinds are still checked. +KUBERNETES_KUBECONFORM_ARGUMENTS: -ignore-missing-schemas +# Block on high and critical findings only. +REPOSITORY_TRIVY_ARGUMENTS: + - --severity + - HIGH,CRITICAL +# SvelteKit's page shell holds %sveltekit.*% placeholders, not finished HTML. +HTML_FILTER_REGEX_EXCLUDE: (src/app\.html) +# CodeQL configuration has no published JSON schema, and Kubernetes manifests are +# validated by kubeconform (v8r would match them to unrelated schemas by file name). +YAML_V8R_FILTER_REGEX_EXCLUDE: (\.github/codeql/|deploy/) diff --git a/.github/workflows/cd.yaml b/.github/workflows/cd.yaml index 41f72b5..8bbf349 100644 --- a/.github/workflows/cd.yaml +++ b/.github/workflows/cd.yaml @@ -11,8 +11,9 @@ jobs: publish: name: Publish # Skipped in the template repo itself (it ships no app); runs in every tenant - # created from this template. - if: github.repository != 'devantler-tech/platform-tenant-template' + # created from this template. The template is matched by its repository ID, + # which survives the rename from platform-tenant-template to application-template. + if: github.repository_id != '1253884448' permissions: contents: read # checkout packages: write # push image + manifests OCI artifact diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 3890169..1f3ddb3 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -320,10 +320,21 @@ jobs: - name: ๐Ÿท๏ธ Validate which dependency updates release run: sh scripts/release-classification.test.sh + # The template's shared MegaLinter checks for workflows, scripts, the Dockerfile, Markdown, YAML, + # JSON, Kubernetes manifests and leaked secrets; ESLint and svelte-check above lint the app's own + # code. Configure it in .mega-linter.yml, which extends the template's base. + megalinter: + name: MegaLinter + # GitHub's `$/` self-repository form fails actionlint until it supports it + # (rhysd/actionlint#711); switch then. + uses: ./.github/workflows/lint.yaml # zizmor: ignore[self-repository] + permissions: + contents: read + ci-required-checks: name: CI - Required Checks runs-on: ubuntu-latest - needs: [lint, check, test, e2e, build, boot-smoke, workflow-caller-pins, readonly-rootfs, publish-pin-approved, validate-retired-links, node-toolchain, release-classification] + needs: [lint, check, test, e2e, build, boot-smoke, workflow-caller-pins, readonly-rootfs, publish-pin-approved, validate-retired-links, node-toolchain, release-classification, megalinter] permissions: actions: read if: ${{ always() }} @@ -345,3 +356,4 @@ jobs: ${{ needs.validate-retired-links.result }} ${{ needs.node-toolchain.result }} ${{ needs.release-classification.result }} + ${{ needs.megalinter.result }} diff --git a/.github/workflows/codeql.yaml b/.github/workflows/codeql.yaml new file mode 100644 index 0000000..f4f1e39 --- /dev/null +++ b/.github/workflows/codeql.yaml @@ -0,0 +1,123 @@ +name: ๐Ÿ” CodeQL + +# Advanced CodeQL setup for every application. The template owns this workflow and +# template-sync keeps it current; tune what it analyses in your own +# `.github/codeql/codeql-config.yml` (queries, paths, query filters). +# +# GitHub refuses advanced results while the repository's CodeQL default setup is on, +# so this stays off until both switches are made, in this order: +# 1. turn default setup off (Settings โ†’ Code security โ†’ CodeQL analysis), then +# 2. set the repository variable CODEQL_SETUP to `advanced`. +# The languages come from the repository's own files, so a new stack needs no edit here. +# Fix its alerts in ordinary reviewed pull requests, never with Copilot Autofix. +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: "27 5 * * 1" # weekly, Monday 05:27 UTC + workflow_dispatch: + +permissions: {} + +concurrency: + group: codeql-${{ github.ref }} + cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} + +jobs: + languages: + name: Detect languages + if: vars.CODEQL_SETUP == 'advanced' + runs-on: ubuntu-latest + permissions: + contents: read # checkout only + outputs: + matrix: ${{ steps.detect.outputs.matrix }} + config: ${{ steps.detect.outputs.config }} + go-mod: ${{ steps.detect.outputs.go-mod }} + steps: + - name: ๐Ÿ”’ Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - name: ๐Ÿ“ฅ Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # Each language CodeQL can analyse is included when a tracked file of its kind + # exists; GitHub Actions workflows are always analysed. + - name: ๐Ÿงญ Detect + id: detect + shell: bash + run: | + set -euo pipefail + entries='{"language":"actions","build-mode":"none"}' + add() { entries="${entries},{\"language\":\"$1\",\"build-mode\":\"$2\"}"; } + has() { [ -n "$(git ls-files -- "$@" | head -n 1)" ]; } + if has 'go.mod' '**/go.mod'; then + add go autobuild + # Set up Go from the root module, or else the first one found below it. + go_mod=go.mod + if ! has 'go.mod'; then go_mod="$(git ls-files -- '**/go.mod' | head -n 1)"; fi + echo "go-mod=${go_mod}" >>"${GITHUB_OUTPUT}" + fi + if has '*.ts' '*.tsx' '*.js' '*.jsx' '*.mjs' '*.cjs' '*.svelte' '*.vue'; then add javascript-typescript none; fi + if has '*.cs' '*.csproj'; then add csharp none; fi + if has '*.py'; then add python none; fi + # Kotlin cannot be analysed without a build; Java alone can. + if has '*.kt'; then add java-kotlin autobuild + elif has '*.java'; then add java-kotlin none; fi + if has '*.rb'; then add ruby none; fi + if has '*.rs'; then add rust none; fi + echo "matrix=[${entries}]" >>"${GITHUB_OUTPUT}" + # An application that has not added its own configuration yet gets the + # security-extended suite instead. + if [ -f .github/codeql/codeql-config.yml ]; then + echo "config=./.github/codeql/codeql-config.yml" >>"${GITHUB_OUTPUT}" + fi + echo "CodeQL languages: [${entries}]" + + analyze: + name: Analyze (${{ matrix.language }}) + needs: [languages] + runs-on: ubuntu-latest + timeout-minutes: 60 + permissions: + contents: read # checkout + actions: read # workflow metadata for the analysis + security-events: write # upload the results to code scanning + strategy: + fail-fast: false + matrix: + include: ${{ fromJSON(needs.languages.outputs.matrix) }} + steps: + - name: ๐Ÿ”’ Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - name: ๐Ÿ“ฅ Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # Autobuild compiles each Go module it finds, with the toolchain go.mod asks for. + - name: โš™๏ธ Set up Go + if: matrix.language == 'go' + uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + with: + go-version-file: ${{ needs.languages.outputs.go-mod }} + cache: false + - name: ๐Ÿ” Initialize CodeQL + uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build-mode }} + config-file: ${{ needs.languages.outputs.config }} + queries: ${{ needs.languages.outputs.config == '' && 'security-extended' || '' }} + - name: ๐Ÿ—๏ธ Autobuild + if: matrix.build-mode == 'autobuild' + uses: github/codeql-action/autobuild@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3 + - name: ๐Ÿ”ฌ Analyze + uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3 + with: + category: /language:${{ matrix.language }} diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml new file mode 100644 index 0000000..3dd9d81 --- /dev/null +++ b/.github/workflows/lint.yaml @@ -0,0 +1,35 @@ +name: ๐Ÿงน Lint + +# Shared lint job, called from ci.yaml so its result counts towards +# CI - Required Checks. The template owns this workflow and template-sync keeps it +# current; configure what it checks in .mega-linter.yml. Go applications do not +# call it: the shared Go validator already runs MegaLinter with signed fixes. +on: + workflow_call: + +permissions: {} + +jobs: + megalinter: + name: MegaLinter + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read # checkout only; findings stay in the job log + steps: + - name: ๐Ÿ”’ Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - name: ๐Ÿ“ฅ Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # Read-only: a finding a linter could fix still fails the job, so fix it locally. + - name: ๐Ÿงน MegaLinter + uses: oxsecurity/megalinter/flavors/cupcake@f2fe8c1cba37091848df3e524066c8c23ef353ed # v10.2.0 + env: + VALIDATE_ALL_CODEBASE: true + APPLY_FIXES: none + # actionlint in MegaLinter does not know the newer `code-quality` permission yet. + ACTION_ACTIONLINT_ARGUMENTS: -ignore code-quality diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index d2b8104..d7947f5 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -9,9 +9,10 @@ permissions: {} jobs: release: - # Skipped in the template repo itself; runs in every tenant created from it. - if: github.repository != 'devantler-tech/platform-tenant-template' - uses: devantler-tech/.github/.github/workflows/create-release.yaml@f33622708f9f25a32acb46cc419007e18a3223b3 # v21.3.1 + # Skipped in the template repo itself; runs in every application created from it. + # The template is matched by its repository ID, which survives renames. + if: github.repository_id != '1253884448' + uses: devantler-tech/.github/.github/workflows/create-release.yaml@3cab796adef97dcde0c55724866a0b19397aba39 # v21.6.2 with: disable-issue-side-effects: true secrets: diff --git a/.github/workflows/stale-issues.yaml b/.github/workflows/stale-issues.yaml index 6266d92..b634c96 100644 --- a/.github/workflows/stale-issues.yaml +++ b/.github/workflows/stale-issues.yaml @@ -23,7 +23,7 @@ jobs: triage: # Keep portfolio automation disabled in external template copies. if: ${{ github.repository_owner == 'devantler-tech' }} - uses: devantler-tech/.github/.github/workflows/triage-stale-issues.yaml@f33622708f9f25a32acb46cc419007e18a3223b3 # v21.3.1 + uses: devantler-tech/.github/.github/workflows/triage-stale-issues.yaml@3cab796adef97dcde0c55724866a0b19397aba39 # v21.6.2 permissions: issues: write actions: write diff --git a/.github/workflows/template-sync.yaml b/.github/workflows/template-sync.yaml index c8d6156..aff7dfb 100644 --- a/.github/workflows/template-sync.yaml +++ b/.github/workflows/template-sync.yaml @@ -10,8 +10,9 @@ permissions: {} jobs: template-sync: # Skipped in the template repo itself (it is the sync source); runs in every - # tenant created from this template, where it opens a PR with template changes. - if: github.repository != 'devantler-tech/platform-tenant-template' + # application created from this template, where it opens a PR with template + # changes. The template is matched by its repository ID, which survives renames. + if: github.repository_id != '1253884448' # The reusable workflow's job opens the sync PR, so the caller must grant it # write to contents + pull-requests. A reusable workflow cannot be granted # more than the caller, and the top-level `permissions: {}` grants none, so @@ -20,7 +21,7 @@ jobs: permissions: contents: write pull-requests: write - uses: devantler-tech/.github/.github/workflows/template-sync.yaml@f33622708f9f25a32acb46cc419007e18a3223b3 # v21.3.1 + uses: devantler-tech/.github/.github/workflows/template-sync.yaml@3cab796adef97dcde0c55724866a0b19397aba39 # v21.6.2 with: source-repo-path: devantler-tech/platform-tenant-template use-app-token: true diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..558bfa0 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,11 @@ +{ + "default": true, + "MD013": false, + "MD024": false, + "MD025": { + "front_matter_title": "" + }, + "MD033": false, + "MD041": false, + "MD060": false +} diff --git a/.mega-linter.yml b/.mega-linter.yml new file mode 100644 index 0000000..143cf87 --- /dev/null +++ b/.mega-linter.yml @@ -0,0 +1,10 @@ +# This application's MegaLinter settings. It extends the shared base, which the +# template owns and template-sync keeps current, so put only what differs here. +# Your values win over the base; the lists named in CONFIG_PROPERTIES_TO_APPEND are +# added to the base's lists instead of replacing them. +# Reference: https://megalinter.io/latest/config-file/ +EXTENDS: .github/mega-linter.base.yml +CONFIG_PROPERTIES_TO_APPEND: + - DISABLE + - DISABLE_LINTERS + - EXCLUDED_DIRECTORIES diff --git a/.stylelintrc.json b/.stylelintrc.json new file mode 100644 index 0000000..8845a12 --- /dev/null +++ b/.stylelintrc.json @@ -0,0 +1,12 @@ +{ + "extends": "stylelint-config-standard", + "rules": { + "import-notation": "string", + "at-rule-no-unknown": [ + true, + { + "ignoreAtRules": ["theme", "source", "utility", "variant", "custom-variant", "plugin", "config", "reference", "apply"] + } + ] + } +} diff --git a/.templatesyncignore b/.templatesyncignore index da663dc..8df075d 100644 --- a/.templatesyncignore +++ b/.templatesyncignore @@ -1,9 +1,10 @@ # Files this tenant owns โ€” template-sync (from devantler-tech/platform-tenant-template) -# must never overwrite them. The template only ships the files below plus the -# shared plumbing it keeps in sync (cd.yaml, release.yaml, template-sync.yaml, -# CLAUDE.md, zizmor.yml and the portable scripts/workflow-caller-pin-contract.test.sh, -# scripts/publish-pin-approved.sh and its test), so only the tenant-owned -# scaffolding needs listing here. +# must never overwrite them. Everything not listed is shared plumbing the template +# keeps in sync: cd.yaml, release.yaml, template-sync.yaml, stale-issues.yaml, +# codeql.yaml, lint.yaml, .github/mega-linter.base.yml, .coderabbit.yaml, +# .markdownlint.json, .yamllint.yml, renovate.json, docs/REFERENCE.md, CLAUDE.md, +# zizmor.yml and the portable scripts/workflow-caller-pin-contract.test.sh, +# scripts/publish-pin-approved.sh and its test. AGENTS.md .claude/skills/maintain/SKILL.md .github/workflows/ci.yaml @@ -18,12 +19,22 @@ LICENSE deploy/ .templatesyncignore +# This tenant's overlays on the shared MegaLinter and CodeQL configuration. +.mega-linter.yml +.github/codeql/codeql-config.yml + # Template scaffolding โ€” dead code in a live tenant; keep ignored so a # template-sync never re-introduces it (deleted here, lives only in the template). scripts/rename-placeholders.sh scripts/rename-placeholders.test.sh .github/workflows/validate-scaffold.yaml +# The scaffold and its stacks build a new application once; they are template-only. +stacks/ +scripts/scaffold.sh +scripts/scaffold.test.sh +.github/workflows/validate-stacks.yaml + # Template-only validation contracts depend on scaffold and Platform fixtures # that do not exist in a live tenant. scripts/agent-instructions.test.sh diff --git a/.yamllint.yml b/.yamllint.yml new file mode 100644 index 0000000..294d0c7 --- /dev/null +++ b/.yamllint.yml @@ -0,0 +1,17 @@ +--- +# Shared yamllint rules for every application made from application-template. The +# template owns this file and template-sync keeps it current; list it in +# .templatesyncignore to diverge. +extends: default +rules: + # GitHub Actions' `on:` key is not a boolean. + truthy: + check-keys: false + # Manifests and workflows rarely start with `---`, and long lines carry URLs and expressions. + document-start: disable + line-length: disable + # One space before an inline comment, as Prettier writes it. + comments: + min-spaces-from-content: 1 + # A section comment sits at the level of the block it opens or closes. + comments-indentation: disable diff --git a/Dockerfile b/Dockerfile index 0cfcb44..2055fbc 100644 --- a/Dockerfile +++ b/Dockerfile @@ -7,8 +7,7 @@ WORKDIR /app COPY package.json package-lock.json* ./ RUN npm ci COPY . . -RUN npm run build -RUN npm prune --production +RUN npm run build && npm prune --production FROM node:26-alpine@sha256:6f08a523443ddedf52941874c203475b0ad503e859ad70cb26ab8be9a517dbd5 WORKDIR /app @@ -19,7 +18,10 @@ COPY --from=build /app/drizzle ./drizzle ENV NODE_ENV=production ENV PORT=3000 EXPOSE 3000 +# 127.0.0.1, not localhost: inside the image localhost resolves to ::1 first, and the server +# listens on IPv4 only, so the old check was refused and never reported healthy. HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ - CMD wget -q -t 1 --spider http://localhost:3000/login || exit 1 -USER node + CMD ["sh", "-c", "wget -q -t 1 --spider http://127.0.0.1:3000/login || exit 1"] +# The node image's `node` user, by number so Kubernetes can verify runAsNonRoot. +USER 1000 CMD ["node", "build/index.js"] diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 90aabf9..8e1d06f 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -1,18 +1,48 @@ # Template reference -The detail behind the [README](../README.md): what the placeholder rename changes, which files the -template keeps in sync and which are yours, how publishing works, and how to validate the template -locally. +The detail behind the [README](../README.md): what the scaffold and the placeholder rename change, +which files the template keeps in sync and which are yours, how publishing works, and how to validate +the template locally. + +## What the scaffold changes + +`scripts/scaffold.sh [--tenancy] [name]` runs once in a repository created from +this template. `name` defaults to the checkout's directory name and must be a DNS-1123 label equal +to the repository name. + +- **Stack.** `go`, `dotnet` and `svelte` copy `stacks//` over the template: the source and tests, + lint and analyzer configuration, a Dockerfile, and the stack's CI job, which replaces the + placeholder `stack` job in `.github/workflows/ci.yaml`. The stack's Dependabot ecosystem is + appended to `.github/dependabot.yml` and its `## Stack` and `## Validation` text replaces the + placeholders in `AGENTS.md`. The Go module becomes `github.com/devantler-tech/`; the .NET + solution, projects and namespace become the PascalCase form of ``; the SvelteKit package + becomes ``. `none` keeps the placeholder job, and with `--tenancy` the placeholder + Dockerfile, for a stack you bring yourself; without `--tenancy` you add your own build files. + Every stack except Go keeps the `lint` job, which calls the shared MegaLinter workflow; a Go + application drops it because the shared Go validator already runs MegaLinter. +- **Tenancy.** With `--tenancy` the application stays a platform tenant: `deploy/`, `cd.yaml`, + the image's Dependabot entry, `renovate.json` and the CI jobs that guard the image and manifests + stay, and + `scripts/rename-placeholders.sh` renames `deploy/` (below). Without it, all of them are + removed and the tenant-only template files are added to `.templatesyncignore`, so template-sync + never brings them back. +- **Template machinery.** `stacks/`, the scaffold, the template's own validation workflows and its + scaffold-time tests are removed; `.templatesyncignore` already lists each of them. + +The edits follow `stack`, `lint`, `tenancy` and `template` markers in `ci.yaml`, `dependabot.yml` +and `AGENTS.md`, so none are left behind. The CI aggregate consumes `needs.*.result`, so dropping a job +and its `needs` entry leaves nothing else to edit. The scaffold refuses an unknown stack or option, +an invalid name, a second run and the upstream template checkout before it changes anything. ## What the rename changes -`scripts/rename-placeholders.sh` rewrites the `app`, `REPLACE_ME`, and `replace-me` +With `--tenancy`, `scripts/scaffold.sh` runs `scripts/rename-placeholders.sh`, which rewrites the `app`, `REPLACE_ME`, and `replace-me` placeholders in `deploy/` consistently, including the container name, Vault role, and ServiceAccount. Those values **must** equal the repository name (see the convention under [How publishing works](#how-publishing-works)). The helper preserves the `app.kubernetes.io/name` label *keys*, CloudNativePG's literal `-app` secret suffix, and the `openbao` SecretStore name. Doing this by hand is easy to get -half-wrong. It's a one-shot helper, so delete it once adopted. +half-wrong. It's a one-shot helper: the scaffold removes it once it has run. The example route is renamed for both environments: `.platform.lan` locally and `.platform.devantler.tech` in production, both in @@ -45,24 +75,34 @@ restore the tailored guide and commit the ignore entry before merging it; changing the ignore file does not undo an existing proposal. To receive a file the template excludes, add the line `!` to your list. -**Owned by the template (kept in sync โ€” do not edit in your tenant):** +**Owned by the template (kept in sync โ€” do not edit in your application).** Rows marked +*tenant* exist only in platform tenants; an application scaffolded without `--tenancy` ignores them: | File | Purpose | |---|---| -| `.github/workflows/cd.yaml` | On a `v*` tag, calls `publish-app.yaml` to build, digest-pin, push, and **cosign-sign** the image + manifests OCI artifact | +| `.github/workflows/cd.yaml` (*tenant*) | On a `v*` tag, calls `publish-app.yaml` to build, digest-pin, push, and **cosign-sign** the image + manifests OCI artifact | | `.github/workflows/release.yaml` | semantic-release on `main` (cuts the `v*` tags that drive `cd.yaml`) | +| `.github/workflows/codeql.yaml` | Advanced CodeQL for the languages found in the repository, reading `.github/codeql/codeql-config.yml`; off until default setup is off and `CODEQL_SETUP=advanced` | +| `.github/workflows/lint.yaml`, `.github/mega-linter.base.yml` | The shared MegaLinter job `ci.yaml` calls, and the base configuration `.mega-linter.yml` extends | +| `.markdownlint.json` | The shared Markdown rules MegaLinter applies | +| `.yamllint.yml` | The shared YAML rules MegaLinter applies | +| `.coderabbit.yaml` | Shared CodeRabbit settings, layered over the organization's with `inheritance: true` | +| `renovate.json` (*tenant*) | Renovate for `deploy/` image tags and Helm charts only, extending the organization preset; Dependabot keeps everything else | | `.github/workflows/template-sync.yaml` | Opens the weekly template-sync PR | | `CLAUDE.md` | `@AGENTS.md` shim | | `docs/REFERENCE.md` | This reference | -| `scripts/workflow-caller-pin-contract.test.sh` | Runs in each tenant's required CI and rejects malformed, divergent, or rolled-back reusable-workflow pins, and a version comment that does not name the tag of the pinned commit | -| `scripts/publish-pin-approved.sh`, `scripts/publish-pin-approved.test.sh` | The check a tenant's required CI runs to refuse a changed publisher identity until Platform approves it for that tenant. Legacy revisions use the existing approved set; maintained publishers require an exact canonical approval. The default `ci.yaml` runs the `publish-pin-approved` job and includes it in `ci-required-checks`; this unregistered template runs its tests only. Older tenants that own `ci.yaml` add the job themselves | +| `scripts/workflow-caller-pin-contract.test.sh` (*tenant*) | Runs in each tenant's required CI and rejects malformed, divergent, or rolled-back reusable-workflow pins, and a version comment that does not name the tag of the pinned commit | +| `scripts/publish-pin-approved.sh`, `scripts/publish-pin-approved.test.sh` (*tenant*) | The check a tenant's required CI runs to refuse a changed publisher identity until Platform approves it for that tenant. Legacy revisions use the existing approved set; maintained publishers require an exact canonical approval. The default `ci.yaml` runs the `publish-pin-approved` job and includes it in `ci-required-checks`; this unregistered template runs its tests only. Older tenants that own `ci.yaml` add the job themselves | | `zizmor.yml` | GitHub Actions pinning policy enforced by the security scan | -**Scaffold-time only (arrives when the repo is created โ€” never re-synced, so a -tenant still carrying these from an older sync can delete them for good):** +**Scaffold-time only (arrives when the repo is created, is removed by `scripts/scaffold.sh`, and is +never re-synced, so a tenant still carrying these from an older sync can delete them for good):** | File | Purpose | |---|---| +| `stacks/` | The Go and .NET stack sources the scaffold copies once; the copies are then yours | +| `scripts/scaffold.sh` (+ its test) | One-shot stack and tenancy scaffold; its test scaffolds every combination and checks what each leaves | +| `.github/workflows/validate-stacks.yaml` | Scaffolds each stack as a tenant, then builds, tests, lints, renders `deploy/`, builds the image and checks it serves `GET /` under the restricted container settings | | `.github/workflows/validate-scaffold.yaml` | Renders `deploy/`, schema-validates every resource, applies the live Platform/shared Kyverno policies, and exercises a pinned Kubernetes API. The live checks prove the template publishes through the pinned signing workflow; Platform still wires the private GHCR pull credential to the tenant identity and cosign-verifying OCI source; and Flux consumes that source while impersonating and targeting the managed `restricted` namespace for both KRO and manual registrations. They then prove the Deployment passes Pod Security `restricted`, the tenant identity can reconcile every rendered kind, and cluster-scoped or interactive privileges remain denied. It gates template PRs, re-validates `main` after every merge, and rechecks upstream drift every day at 06:17 UTC (or on manual dispatch), keeping one tracking issue open while that scheduled check fails on `main`; structural mutation tests keep every layer fail-closed. The workflow no-ops in tenants and is scaffold-time only | | `scripts/rename-placeholders.sh` (+ its test) | One-shot rename of the placeholder app to your tenant name | | `scripts/agent-instructions.test.sh` | Fails closed if the one-time agent scaffold loses its ownership, dependency-bot, external-code, exact-head review, pinned-merge, or user-path evaluation boundaries, or regains a retired rule | @@ -83,6 +123,8 @@ AGENTS.md .github/CODEOWNERS .github/workflows/ci.yaml .github/dependabot.yml +.mega-linter.yml +.github/codeql/codeql-config.yml .releaserc .gitignore Dockerfile @@ -92,8 +134,12 @@ LICENSE deploy/ .templatesyncignore -# Template scaffolding โ€” dead code in a live tenant; keep ignored so a +# Template scaffolding โ€” dead code in a live application; keep ignored so a # template-sync never re-introduces it after you delete it. +stacks/ +scripts/scaffold.sh +scripts/scaffold.test.sh +.github/workflows/validate-stacks.yaml scripts/rename-placeholders.sh scripts/rename-placeholders.test.sh scripts/agent-instructions.test.sh @@ -110,6 +156,13 @@ scripts/platform-network-floor-contract.test.sh scripts/platform-vpa-floor.test.sh scripts/platform-vpa-floor-contract.test.sh .github/workflows/validate-scaffold.yaml + +# Only without --tenancy: the tenant plumbing the scaffold removed. +.github/workflows/cd.yaml +renovate.json +scripts/publish-pin-approved.sh +scripts/publish-pin-approved.test.sh +scripts/workflow-caller-pin-contract.test.sh ``` `AGENTS.md` and the `maintain` skill ship as scaffolding (a starting point for new @@ -184,7 +237,7 @@ head, using only Actions read access. It requires a complete clear snapshot in addition to successful tenant jobs. Separate workflows still need their own required checks for failures that happen after that snapshot. -Run these from the repository root. In every tenant, and in this template: +Run these from the repository root. In every platform tenant, and in this template: ```sh kubectl kustomize deploy/ # manifests build @@ -198,6 +251,7 @@ scaffold-time scripts, but template sync never updates them, so a tenant that keeps them runs them against stale copies; live tenants delete and ignore them: ```sh +sh scripts/scaffold.test.sh # stack and tenancy scaffold, every combination sh scripts/rename-placeholders.test.sh # onboarding contract sh scripts/agent-instructions.test.sh # agent safety contract sh scripts/workflow-caller-contract.test.sh # template-only caller/scaffold contract diff --git a/renovate.json b/renovate.json new file mode 100644 index 0000000..5429269 --- /dev/null +++ b/renovate.json @@ -0,0 +1,21 @@ +{ + "$schema": "https://docs.renovatebot.com/renovate-schema.json", + "description": [ + "Renovate only fills Dependabot's gaps: the image tags and Helm charts in deploy/.", + "Dependabot keeps packages, GitHub Actions and the Dockerfile current, so Renovate's other managers stay off and no update arrives twice.", + "The template owns this file; list it in .templatesyncignore to diverge." + ], + "extends": ["github>devantler-tech/.github:renovate-config"], + "enabledManagers": ["kubernetes", "kustomize"], + "kubernetes": { + "managerFilePatterns": ["/^deploy/.+\\.ya?ml$/"] + }, + "packageRules": [ + { + "description": "cd.yaml pins this application's own image digest at release time.", + "matchDatasources": ["docker"], + "matchPackageNames": ["ghcr.io/devantler-tech/**"], + "enabled": false + } + ] +} diff --git a/src/app.css b/src/app.css index 3ba6bbb..d3f01a3 100644 --- a/src/app.css +++ b/src/app.css @@ -1,6 +1,7 @@ @import 'tailwindcss'; @theme { + /* Colours */ --color-cream: #F0DFCC; --color-warm-white: #FFF8F0; --color-sand: #D4B89C; @@ -8,6 +9,7 @@ --color-dark-brown: #3D2E1F; --color-soft-gold: #C9A96E; + /* Fonts */ --font-serif: 'Cormorant Garamond', serif; --font-sans: 'Inter', sans-serif; --font-script: 'Pinyon Script', cursive;