feat(ci): reusable ecosystem workflows + selftest (999_testing)

The ecosystem-CI architecture: reusable Forgejo workflows (on: workflow_call)
that downstream repos reference as
`uses: olsitec/foundation/.forgejo/workflows/<x>.yml@master`.

- reusable-node-build.yml: install + build for npm/bun/none — covers the npm
  package (olsicrypto), bun package (document-engine), and no-artifact versioned
  (olsitrack/api) shapes.
- reusable-docker-build.yml: docker build via the host socket (R5: trusted repos
  only until the runner is fenced) — the seaspots-homepage / token-service shape.
- reusable-lint.yml: eslint + yamllint gate (either error → job non-zero).
- reusable-semantic-release.yml: conventionalcommits-preset version probe (dry-run),
  faithful to the GitLab template; outputs the computed next version. Real Forgejo
  publishing deferred (no @semantic-release/forgejo analogue yet).

- ecosystem-selftest.yml + ci/semantic-release-bumptest.sh: self-contained proof
  on the runner of the 999_testing acceptance criteria that need no external repo —
  the semantic-release bump sequence (1.0.0→1.1.0→1.1.1→2.0.0→3.0.0) and the
  eslint/yamllint non-zero-exit gates. Validated in a foundation-ci container.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.forgejo/workflows/ecosystem-selftest.yml

@@ -0,0 +1,66 @@
+# ecosystem-selftest — proves the foundation's ecosystem-CI capabilities on its own
+# runner (documentation/999_testing.md), without depending on external candidate
+# repos. Three self-contained jobs, each asserting an acceptance criterion:
+#   - semantic-release: the bump sequence 1.0.0→1.1.0→1.1.1→2.0.0→3.0.0
+#   - eslint-gate:      an eslint error makes the job exit non-zero
+#   - yamllint-gate:    a yamllint error makes the job exit non-zero
+# Build-shape coverage (npm/bun/docker) is exercised by the reusable-* workflows
+# against the real candidate repos; this file guards the capabilities that need no
+# external repo. Runs in the baked foundation-ci image.
+name: ecosystem-selftest
+on:
+  push:
+    paths:
+      - "ci/**"
+      - ".forgejo/workflows/ecosystem-selftest.yml"
+      - ".forgejo/workflows/reusable-*.yml"
+  workflow_dispatch:
+
+jobs:
+  semantic-release-bumptest:
+    runs-on: docker
+    container:
+      image: foundation-ci:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: semantic-release bump sequence
+        run: ./ci/semantic-release-bumptest.sh
+
+  eslint-gate:
+    runs-on: docker
+    container:
+      image: foundation-ci:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: an eslint error must fail the job (exit non-zero)
+        run: |
+          set -e
+          d=$(mktemp -d); cd "$d"
+          # flat config (eslint 9) with no-unused-vars as an error
+          cat > eslint.config.mjs <<'EOF'
+          export default [{ rules: { "no-unused-vars": "error" } }];
+          EOF
+          printf 'const x = 1;\n' > bad.js   # x is unused → error
+          if eslint bad.js; then
+            echo "BUG: eslint passed on a file with an error"; exit 1
+          else
+            echo "OK: eslint exited non-zero on the lint error"
+          fi
+
+  yamllint-gate:
+    runs-on: docker
+    container:
+      image: foundation-ci:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: a yamllint error must fail the job (exit non-zero)
+        run: |
+          set -e
+          d=$(mktemp -d); cd "$d"
+          # duplicate key + bad indentation → yamllint error
+          printf 'a: 1\na: 2\n' > bad.yaml
+          if yamllint -d '{extends: default, rules: {document-start: disable}}' bad.yaml; then
+            echo "BUG: yamllint passed on a file with a duplicate key"; exit 1
+          else
+            echo "OK: yamllint exited non-zero on the lint error"
+          fi

.forgejo/workflows/reusable-docker-build.yml

@@ -0,0 +1,67 @@
+# reusable-docker-build — build a Docker image (999_testing candidates C1/C5).
+#
+# A REUSABLE workflow (on: workflow_call) downstream repos call:
+#   jobs:
+#     image:
+#       uses: olsitec/foundation/.forgejo/workflows/reusable-docker-build.yml@master
+#       with: { image: "olsitec/seaspots-homepage:ci", push: false }
+#
+# Builds against the HOST Docker daemon via the mounted socket (the foundation-ci
+# image ships the docker CLI; the runner's valid_volumes allows the mount). NOTE
+# (R5): the host socket is root-equivalent on the forge VM — this is acceptable
+# ONLY for trusted first-party repos until the runner is fenced to its own VM.
+#
+# Candidates C1 (seaspots-homepage) and C5 (token-service) depend on @olsitec
+# packages from a private registry that is not published yet (Stage-2). Their real
+# builds need a registry / npmrc; this workflow proves the docker-build path and
+# accepts a `build-args`/`npmrc` hook for when the registry exists.
+name: reusable-docker-build
+on:
+  workflow_call:
+    inputs:
+      context:
+        type: string
+        default: "."
+      dockerfile:
+        type: string
+        default: "Dockerfile"
+      image:
+        description: "image ref to tag, e.g. name:tag"
+        type: string
+        required: true
+      build-args:
+        description: "newline-separated KEY=VALUE docker --build-arg pairs"
+        type: string
+        default: ""
+      push:
+        description: "push to the foundation registry after build (registry must exist)"
+        type: boolean
+        default: false
+
+jobs:
+  image:
+    runs-on: docker
+    container:
+      image: foundation-ci:latest
+      volumes:
+        - /var/run/docker.sock:/var/run/docker.sock
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Docker build
+        run: |
+          args=""
+          if [ -n "${{ inputs.build-args }}" ]; then
+            while IFS= read -r kv; do
+              [ -z "$kv" ] && continue
+              args="$args --build-arg $kv"
+            done <<'EOF'
+          ${{ inputs.build-args }}
+          EOF
+          fi
+          echo "+ docker build -f ${{ inputs.dockerfile }} -t ${{ inputs.image }} $args ${{ inputs.context }}"
+          docker build -f "${{ inputs.dockerfile }}" -t "${{ inputs.image }}" $args "${{ inputs.context }}"
+
+      - name: Push
+        if: ${{ inputs.push }}
+        run: docker push "${{ inputs.image }}"

.forgejo/workflows/reusable-lint.yml

@@ -0,0 +1,63 @@
+# reusable-lint — eslint + yamllint gate (999_testing "linter testing").
+#
+# A REUSABLE workflow (on: workflow_call). Either linter finding an error makes
+# the job exit non-zero (the acceptance criterion). Prefers the project's own
+# pinned eslint (node_modules/.bin) for config/plugin fidelity, falling back to
+# the foundation-ci image's global eslint; yamllint comes from the image.
+#
+#   jobs:
+#     lint:
+#       uses: olsitec/foundation/.forgejo/workflows/reusable-lint.yml@master
+#       with: { eslint-paths: ".", yamllint-paths: "." }
+name: reusable-lint
+on:
+  workflow_call:
+    inputs:
+      eslint:
+        type: boolean
+        default: true
+      yamllint:
+        type: boolean
+        default: true
+      eslint-paths:
+        type: string
+        default: "."
+      yamllint-paths:
+        type: string
+        default: "."
+      package-manager:
+        description: "bun | npm | none — to install project-local eslint config/plugins"
+        type: string
+        default: bun
+
+jobs:
+  lint:
+    runs-on: docker
+    container:
+      image: foundation-ci:latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies (project-local eslint config/plugins)
+        if: ${{ inputs.eslint }}
+        run: |
+          case "${{ inputs.package-manager }}" in
+            bun)  bun install --frozen-lockfile || bun install || true ;;
+            npm)  npm ci || npm install || true ;;
+            none) echo "skip install" ;;
+          esac
+
+      - name: eslint
+        if: ${{ inputs.eslint }}
+        run: |
+          if [ -x node_modules/.bin/eslint ]; then
+            echo "+ project eslint"; node_modules/.bin/eslint ${{ inputs.eslint-paths }}
+          else
+            echo "+ image eslint"; eslint ${{ inputs.eslint-paths }}
+          fi
+
+      - name: yamllint
+        if: ${{ inputs.yamllint }}
+        run: |
+          echo "+ yamllint ${{ inputs.yamllint-paths }}"
+          yamllint ${{ inputs.yamllint-paths }}

.forgejo/workflows/reusable-node-build.yml

@@ -0,0 +1,58 @@
+# reusable-node-build — build/test an npm- or bun-based project (999_testing).
+#
+# A REUSABLE workflow (on: workflow_call) downstream repos call:
+#   jobs:
+#     build:
+#       uses: olsitec/foundation/.forgejo/workflows/reusable-node-build.yml@master
+#       with: { package-manager: bun, build: "bun run build" }
+#
+# Runs in the baked foundation-ci image (bun + node present). Covers the
+# non-Docker candidate shapes: npm package built with npm (olsicrypto), bun
+# package built with bun (document-engine), and the no-build / versioned-only
+# utility (olsitrack/api) via an empty `build`.
+name: reusable-node-build
+on:
+  workflow_call:
+    inputs:
+      package-manager:
+        description: "bun | npm | none (none = skip install)"
+        type: string
+        default: bun
+      build:
+        description: "build command to run verbatim (empty = skip, e.g. no-artifact repos)"
+        type: string
+        default: ""
+      workdir:
+        description: "working directory for install + build"
+        type: string
+        default: "."
+
+jobs:
+  build:
+    runs-on: docker
+    container:
+      image: foundation-ci:latest
+    defaults:
+      run:
+        working-directory: ${{ inputs.workdir }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies (${{ inputs.package-manager }})
+        run: |
+          case "${{ inputs.package-manager }}" in
+            bun)  bun install --frozen-lockfile || bun install ;;
+            npm)  npm ci || npm install ;;
+            none) echo "package-manager=none → skipping install" ;;
+            *)    echo "unknown package-manager '${{ inputs.package-manager }}'" >&2; exit 1 ;;
+          esac
+
+      - name: Build
+        run: |
+          cmd='${{ inputs.build }}'
+          if [ -z "$cmd" ]; then
+            echo "no build command (non-artifact / versioned-only repo) — install-only check passed"
+            exit 0
+          fi
+          echo "+ $cmd"
+          eval "$cmd"

.forgejo/workflows/reusable-semantic-release.yml

@@ -0,0 +1,81 @@
+# reusable-semantic-release — compute the next semver from conventional commits
+# (999_testing "semantic-release testing"). Mirrors the canonical GitLab template
+# (olsitec/gitlab ci_templates/release-automation/semantic-release.yaml): the
+# conventionalcommits preset + Olsitec's releaseRules, run as a `--dry-run --no-ci
+# --tag-format '${version}'` version probe. Exposes the computed version as an output.
+#
+#   jobs:
+#     version:
+#       uses: olsitec/foundation/.forgejo/workflows/reusable-semantic-release.yml@master
+#     build:
+#       needs: version
+#       runs-on: docker
+#       steps: [ run: echo "releasing ${{ needs.version.outputs.version }}" ]
+#
+# NOTE: dry-run only — it computes/prints the next version (the part exercised by
+# 999_testing and the GitLab `generate-release-version` job). Actually PUBLISHING a
+# release to Forgejo (tag + release + changelog) needs a Forgejo-side publish step
+# and a token; that is deferred until the package/release flow is wired (the GitLab
+# template publishes via @semantic-release/gitlab, which has no Forgejo analogue yet).
+name: reusable-semantic-release
+on:
+  workflow_call:
+    inputs:
+      branch:
+        type: string
+        default: master
+    outputs:
+      version:
+        description: "next release version (empty if the commits warrant no release)"
+        value: ${{ jobs.version.outputs.version }}
+
+jobs:
+  version:
+    runs-on: docker
+    container:
+      image: foundation-ci:latest
+    outputs:
+      version: ${{ steps.compute.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # semantic-release needs full history + tags
+
+      - name: Write .releaserc.yaml (Olsitec conventionalcommits ruleset)
+        run: |
+          cat > .releaserc.yaml <<'EOF'
+          branches:
+            - name: ${{ inputs.branch }}
+          tagFormat: "${version}"
+          plugins:
+            - - "@semantic-release/commit-analyzer"
+              - preset: conventionalcommits
+                releaseRules:
+                  - { breaking: true, release: major }
+                  - { type: breaking, release: major }
+                  - { type: feature, release: minor }
+                  - { type: feat, release: minor }
+                  - { type: fix, release: patch }
+                  - { type: build, release: patch }
+                  - { type: chore, release: patch }
+                  - { type: ci, release: patch }
+                  - { type: docs, release: patch }
+                  - { type: perf, release: patch }
+                  - { type: refactor, release: patch }
+                  - { type: style, release: patch }
+                  - { type: test, release: patch }
+                parserOpts:
+                  noteKeywords: [ "BREAKING CHANGE", "BREAKING CHANGES" ]
+            - "@semantic-release/release-notes-generator"
+          EOF
+
+      - name: Compute next version (dry-run)
+        id: compute
+        run: |
+          out=$(semantic-release --dry-run --no-ci --tag-format '${version}' --branches "${{ inputs.branch }}" 2>&1 || true)
+          printf '%s\n' "$out"
+          ver=$(printf '%s\n' "$out" \
+            | grep -oiE 'next release version is [0-9]+\.[0-9]+\.[0-9]+' \
+            | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | tail -1)
+          echo "computed next version: ${ver:-<none>}"
+          echo "version=$ver" >> "$GITHUB_OUTPUT"