From 406a5448350384d958ac82fac0faa5cf4f947a50 Mon Sep 17 00:00:00 2001
From: Anna Larch <anna@nextcloud.com>
Date: Thu, 17 Sep 2026 15:26:17 +0200
Subject: [PATCH] feat(ci): verify course content against reality

Adds scripts/verify-content.mjs with two modes. Offline checks gate pull
requests: unknown template variables, a literal version that should have
been templated, manifest entries pointing at files nobody wrote. Online
checks run weekly and report rather than gate, because a vendor moving a
URL must not block somebody's typo fix.

The online half is what catches the drift that reading never does: links,
image tags, whether nextcloud-docker-dev still defines the services the
setup module tells readers to start, and whether the pinned version is
still current.

It found three things on its first run: an info.xml missed by the manual
templating pass, a version range quoted in prose, and a broken occ docs
link whose path segment had been dropped.

Assisted-by: ClaudeCode:claude-opus-5
Signed-off-by: Anna Larch <anna@nextcloud.com>
---
 .github/workflows/verify-content.yml |  71 +++++++
 content/php/beginner/1.md            |   2 +-
 content/php/beginner/2.md            |   2 +-
 content/php/beginner/4.md            |   2 +-
 content/php/beginner/8.md            |   2 +-
 package.json                         |   3 +-
 scripts/verify-content.mjs           | 287 +++++++++++++++++++++++++++
 7 files changed, 364 insertions(+), 5 deletions(-)
 create mode 100644 .github/workflows/verify-content.yml
 create mode 100755 scripts/verify-content.mjs

diff --git a/.github/workflows/verify-content.yml b/.github/workflows/verify-content.yml
new file mode 100644
index 0000000..817b110
--- /dev/null
+++ b/.github/workflows/verify-content.yml
@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+name: Verify course content
+
+on:
+  pull_request:
+    paths:
+      - 'content/**'
+      - 'lib/content.ts'
+      - 'scripts/verify-content.mjs'
+      - '.github/workflows/verify-content.yml'
+  schedule:
+    # Weekly, Monday morning. The things this catches - a vendor moving a URL,
+    # an image tag disappearing, nextcloud-docker-dev changing under the setup
+    # module - drift over months, not hours. Running it more often would add
+    # nothing except load on other people's servers.
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  offline:
+    name: Offline checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: node scripts/verify-content.mjs
+
+  online:
+    name: Online checks
+    # Never on pull requests: a dead third-party link must not block somebody's
+    # typo fix. This reports, it does not gate.
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Run online checks
+        id: verify
+        run: |
+          set +e
+          node scripts/verify-content.mjs --online > report.txt 2>&1
+          echo "exit_code=$?" >> "$GITHUB_OUTPUT"
+          cat report.txt
+
+      - name: Report failures
+        if: steps.verify.outputs.exit_code != '0'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TITLE: 'Course content verification is failing'
+        run: |
+          BODY=$(printf 'The weekly content check found problems. Full output:\n\n```\n%s\n```\n\nRun locally with `npm run verify:content -- --online`.\n\n[Workflow run](%s/%s/actions/runs/%s)\n' \
+            "$(cat report.txt)" "$GITHUB_SERVER_URL" "$GITHUB_REPOSITORY" "$GITHUB_RUN_ID")
+          # One issue, kept up to date, rather than a new one every Monday.
+          EXISTING=$(gh issue list --state open --search "in:title \"$TITLE\"" --json number --jq '.[0].number')
+          if [ -n "$EXISTING" ]; then
+            gh issue comment "$EXISTING" --body "$BODY"
+          else
+            gh issue create --title "$TITLE" --body "$BODY" --label documentation
+          fi
diff --git a/content/php/beginner/1.md b/content/php/beginner/1.md
index 96009c0..849053c 100644
--- a/content/php/beginner/1.md
+++ b/content/php/beginner/1.md
@@ -287,7 +287,7 @@ If you're coming from tutorials written for NC32 or NC33, the development enviro
 
 - [nextcloud-docker-dev repository](https://github.com/nextcloud/nextcloud-docker-dev) — source of truth for the Docker environment
 - [Development environment — Nextcloud developer docs](https://docs.nextcloud.com/server/latest/developer_manual/getting_started/devenv.html)
-- [occ command reference — Nextcloud admin docs](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html)
+- [occ command reference — Nextcloud admin docs](https://docs.nextcloud.com/server/{{nextcloudVersion}}/admin_manual/occ_command.html)
 
 <!-- Cross-module links: re-enable once the target modules exist (see academy #16).
 *Next: [Module 2 — App Anatomy](./php-beginner-m2-app-anatomy.md)*  
diff --git a/content/php/beginner/2.md b/content/php/beginner/2.md
index ea5682b..4d732f9 100644
--- a/content/php/beginner/2.md
+++ b/content/php/beginner/2.md
@@ -140,7 +140,7 @@ The `FileCopyrightText` line records who holds copyright and when. The `License-
 
 For PHP, NC34 supports 8.2 (deprecated), 8.3, 8.4, and 8.5 (recommended). We set `min-version="8.3"` to avoid the deprecated 8.2 — there's no practical reason to support it for a new app. For future reference, the supported PHP versions for any Nextcloud release are listed on the [Nextcloud system requirements page](https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html).
 
-For the Nextcloud version range, setting both `min-version="34"` and `max-version="34"` is intentional for now — it prevents your app from being enabled on instances older than NC34 where APIs may differ, and from being silently enabled on an NC35 instance where you haven't tested it yet. You'll update this as you verify compatibility.
+For the Nextcloud version range, setting both `min-version="{{nextcloudVersion}}"` and `max-version="{{nextcloudVersion}}"` is intentional for now — it prevents your app from being enabled on instances older than NC34 where APIs may differ, and from being silently enabled on an NC35 instance where you haven't tested it yet. You'll update this as you verify compatibility.
 
 **`<navigation>`** is what puts your app in the top navigation bar. The `<id>` must match your app ID. The `<icon>` points to a file in your `img/` directory — Nextcloud uses `img/app.svg` and `img/app-dark.svg` for light and dark mode. The `<route>` value `pinboard.page.index` is a route name — we'll define what this means in a moment. This is the simpler of two approaches — the other is registering programmatically via `INavigationManager` in your `Application.php`, which some complex apps (like Talk) use when they need more control. For Pinboard, the `info.xml` approach is correct.
 
diff --git a/content/php/beginner/4.md b/content/php/beginner/4.md
index 606b31c..c636f38 100644
--- a/content/php/beginner/4.md
+++ b/content/php/beginner/4.md
@@ -252,7 +252,7 @@ No `url`, no `title`, no `createdAt`. The request succeeds, the response looks l
 Implementing `JsonSerializable` fixes this by telling `json_encode()` exactly what to output. Two details in the code above:
 
 - **`implements \JsonSerializable`** — the interface declares a single method, `jsonSerialize()`, which returns whatever should be encoded in place of the object. Returning an array of your fields gives you full control over the shape of your API response, including omitting fields you don't want to expose.
-- **`#[\Override]`** — added because `jsonSerialize()` is defined by the interface you just implemented. The attribute tells PHP to verify that: if you typo the name as `jsonSerialise()`, PHP raises a compile-time error instead of silently defining an unrelated method that never gets called. It requires PHP 8.3, which is Nextcloud 34's minimum anyway. This matches how server apps do it — see `Absence` in the DAV app or `VersionEntity` in Files Versions.
+- **`#[\Override]`** — added because `jsonSerialize()` is defined by the interface you just implemented. The attribute tells PHP to verify that: if you typo the name as `jsonSerialise()`, PHP raises a compile-time error instead of silently defining an unrelated method that never gets called. It requires PHP 8.3, which is NC34's minimum anyway. This matches how server apps do it — see `Absence` in the DAV app or `VersionEntity` in Files Versions.
 
 This is the standard pattern in Nextcloud apps: an explicit `jsonSerialize()` per entity, listing the fields the API returns. Note that it also decouples your API from your database schema — renaming a column doesn't have to change your JSON.
 
diff --git a/content/php/beginner/8.md b/content/php/beginner/8.md
index ce6d995..c86ff87 100644
--- a/content/php/beginner/8.md
+++ b/content/php/beginner/8.md
@@ -100,7 +100,7 @@ Each user's pins are private to them. Built as part of the Nextcloud Developer C
   <repository>https://github.com/YOUR_USERNAME/pinboard-php</repository>
   <dependencies>
     <php min-version="8.3"/>
-    <nextcloud min-version="34" max-version="34"/>
+    <nextcloud min-version="{{nextcloudVersion}}" max-version="{{nextcloudVersion}}"/>
   </dependencies>
   <navigations>
     <navigation>
diff --git a/package.json b/package.json
index 6e6da24..46e4b8b 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,8 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "eslint"
+    "lint": "eslint",
+    "verify:content": "node scripts/verify-content.mjs"
   },
   "dependencies": {
     "next": "16.2.12",
diff --git a/scripts/verify-content.mjs b/scripts/verify-content.mjs
new file mode 100755
index 0000000..a35aecc
--- /dev/null
+++ b/scripts/verify-content.mjs
@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * Checks the course content against reality.
+ *
+ * Two modes, on purpose:
+ *
+ *   --offline  (default)  Nothing leaves the machine. Safe to gate every pull
+ *                         request on, because it cannot fail for reasons
+ *                         outside this repository.
+ *   --online              Adds checks against the network: links, the docs
+ *                         site, the nextcloud-docker-dev repo, image tags.
+ *                         Run on a slow timer, never as a PR gate - a vendor
+ *                         rotating a URL must not block somebody's typo fix.
+ *
+ * Exit code is 1 if any check fails, 0 otherwise. Warnings never fail the run.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const ROOT = path.resolve(import.meta.dirname, '..')
+const CONTENT = path.join(ROOT, 'content')
+const ONLINE = process.argv.includes('--online')
+
+const failures = []
+const warnings = []
+const notes = []
+
+const fail = (m) => failures.push(m)
+const warn = (m) => warnings.push(m)
+const note = (m) => notes.push(m)
+
+/** Every markdown file under content/, as [relativePath, text]. */
+function markdownFiles(dir = CONTENT) {
+  const out = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...markdownFiles(full))
+    else if (entry.name.endsWith('.md')) out.push([path.relative(ROOT, full), fs.readFileSync(full, 'utf-8')])
+  }
+  return out
+}
+
+const manifest = JSON.parse(fs.readFileSync(path.join(CONTENT, 'course-manifest.json'), 'utf-8'))
+const PIN = manifest.course?.targetNextcloudVersion
+const VARIABLES = { nextcloudVersion: PIN }
+const KNOWN_VARIABLES = new Set(Object.keys(VARIABLES))
+const files = markdownFiles()
+
+/**
+ * Mirrors substituteVariables() in lib/content.ts. Checks that care about what
+ * the reader ends up seeing - links, above all - must run against the rendered
+ * text, or they check a token instead of a URL.
+ */
+const render = (text) => text.replace(/\{\{(\w+)\}\}/g, (whole, name) => VARIABLES[name] ?? whole)
+
+// ---------------------------------------------------------------- offline ---
+
+function checkPin() {
+  if (!PIN) return fail('course-manifest.json has no course.targetNextcloudVersion')
+  if (!/^\d+$/.test(PIN)) fail(`targetNextcloudVersion should be a bare major, got ${JSON.stringify(PIN)}`)
+}
+
+/** A `{{token}}` nobody substitutes renders literally to the reader. */
+function checkVariablesAreKnown() {
+  for (const [file, text] of files) {
+    for (const m of text.matchAll(/\{\{(\w+)\}\}/g)) {
+      if (!KNOWN_VARIABLES.has(m[1])) fail(`${file}: unknown variable {{${m[1]}}}`)
+    }
+  }
+}
+
+/**
+ * A literal version equal to the pin is a reference somebody forgot to
+ * template, so the next bump will silently leave it behind.
+ */
+function checkPinIsNotHardcoded() {
+  if (!PIN) return
+  const patterns = [
+    new RegExp(`stable${PIN}\\b`, 'g'),
+    new RegExp(`\\bNextcloud ${PIN}\\b`, 'g'),
+    new RegExp(`min-version="${PIN}"`, 'g'),
+  ]
+  for (const [file, text] of files) {
+    for (const re of patterns) {
+      for (const m of text.matchAll(re)) {
+        const line = text.slice(0, m.index).split('\n').length
+        warn(`${file}:${line}: literal "${m[0]}" - should this be {{nextcloudVersion}}?`)
+      }
+    }
+  }
+}
+
+/**
+ * The checklist a human works through when the pin moves. These are claims true
+ * of one release and not the next, which is exactly why they are NOT templated:
+ * substituting them would turn a visibly stale number into a confidently wrong
+ * sentence. See AGENTS.md.
+ */
+function listReleaseSpecificClaims() {
+  const re = /\bNC(\d+)\b|\bNextcloud (\d+)\b/g
+  const found = []
+  for (const [file, text] of files) {
+    const lines = text.split('\n')
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        const version = m[1] ?? m[2]
+        if (version === PIN) continue // covered by checkPinIsNotHardcoded
+        found.push(`${file}:${i + 1}: mentions NC${version} - ${line.trim().slice(0, 100)}`)
+      }
+    })
+  }
+  if (found.length) {
+    note(`${found.length} release-specific references to re-read when the pin moves:`)
+    found.forEach((f) => note(`    ${f}`))
+  }
+}
+
+/** A manifest entry pointing at a file nobody wrote renders as a dead module. */
+function checkStandaloneFilesExist() {
+  const categories = manifest.standalone?.categories ?? {}
+  for (const [catId, cat] of Object.entries(categories)) {
+    for (const mod of cat.modules ?? []) {
+      if (!mod.file) continue
+      const full = path.join(CONTENT, mod.file)
+      if (!fs.existsSync(full)) fail(`manifest standalone ${catId}/${mod.id}: missing content file ${mod.file}`)
+    }
+  }
+}
+
+// ----------------------------------------------------------------- online ---
+
+/**
+ * URLs that are illustrations rather than destinations: local addresses the
+ * reader will run themselves, and stand-ins they are meant to replace with
+ * their own. Checking these produces permanent noise, and noise is how a
+ * report stops being read.
+ */
+const PLACEHOLDER =
+  /localhost|127\.0\.0\.1|0\.0\.0\.0|\.local\b|example\.com|host\.docker\.internal|YOUR_|your-nextcloud|<[^>]*>|PORT/
+
+const seen = new Map()
+async function head(url, { retries = 1 } = {}) {
+  if (seen.has(url)) return seen.get(url)
+  let status = 0
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(url, { method: 'GET', redirect: 'follow', signal: AbortSignal.timeout(25_000) })
+      status = res.status
+      if (status < 400) break
+    } catch {
+      status = 0
+    }
+    if (attempt < retries) await new Promise((r) => setTimeout(r, 1500))
+  }
+  seen.set(url, status)
+  // Deliberately unhurried: this runs on a timer, not in anybody's way, and
+  // being polite to other people's servers costs us nothing here.
+  await new Promise((r) => setTimeout(r, 300))
+  return status
+}
+
+async function checkLinks() {
+  const urls = new Set()
+  for (const [, raw] of files) {
+    const text = render(raw)
+    for (const m of text.matchAll(/https?:\/\/[^\s)<>"'`\]]+/g)) {
+      const url = m[0].replace(/[.,;:]+$/, '')
+      if (PLACEHOLDER.test(url)) continue
+      urls.add(url)
+    }
+  }
+  note(`checking ${urls.size} unique links`)
+  for (const url of urls) {
+    const status = await head(url)
+    if (status === 0) warn(`link unreachable: ${url}`)
+    // 403 and 429 mean the server dislikes CI, not that the page is gone.
+    else if (status === 403 || status === 429) warn(`link ${status} (bot-blocked?): ${url}`)
+    else if (status >= 400) fail(`link ${status}: ${url}`)
+  }
+}
+
+/** Is the version the course targets still the current one? */
+async function checkPinAgainstDocs() {
+  if (!PIN) return
+  const pinned = `https://docs.nextcloud.com/server/${PIN}/admin_manual/installation/system_requirements.html`
+  if ((await head(pinned)) >= 400) fail(`no admin manual for the pinned version: ${pinned}`)
+
+  try {
+    const res = await fetch('https://docs.nextcloud.com/server/stable/admin_manual/installation/system_requirements.html', {
+      redirect: 'follow',
+      signal: AbortSignal.timeout(25_000),
+    })
+    const title = (await res.text()).match(/<title>[^<]*Nextcloud (\d+)/)
+    if (!title) return warn('could not read the current stable version from the docs site')
+    const stable = Number(title[1])
+    if (Number(PIN) < stable) {
+      warn(`the course targets Nextcloud ${PIN}; current stable is ${stable}. Consider bumping course.targetNextcloudVersion.`)
+      note(`  system requirements for ${PIN}: https://docs.nextcloud.com/server/${PIN}/admin_manual/installation/system_requirements.html`)
+      note(`  ...and for ${stable}: https://docs.nextcloud.com/server/${stable}/admin_manual/installation/system_requirements.html`)
+      note('  Compare the PHP versions and re-read the release-specific claims listed above before bumping.')
+    }
+  } catch {
+    warn('docs.nextcloud.com unreachable')
+  }
+}
+
+/**
+ * The setup module tells readers to run specific things in a repository we do
+ * not control. This is the check that would have caught the hosts step going
+ * stale, and the stableXX container needing its own checkout.
+ */
+async function checkDockerDev() {
+  const raw = (f) => `https://raw.githubusercontent.com/nextcloud/nextcloud-docker-dev/master/${f}`
+  const get = async (f) => {
+    try {
+      const res = await fetch(raw(f), { signal: AbortSignal.timeout(25_000) })
+      return res.ok ? await res.text() : null
+    } catch {
+      return null
+    }
+  }
+
+  const compose = await get('docker-compose.yml')
+  if (!compose) return warn('could not fetch nextcloud-docker-dev/docker-compose.yml')
+
+  for (const service of ['nextcloud', 'proxy', `stable${PIN}`]) {
+    if (!new RegExp(`^\\s{2}${service}:`, 'm').test(compose)) {
+      fail(`nextcloud-docker-dev no longer defines the "${service}" service, which the setup module tells readers to start`)
+    }
+  }
+
+  const bootstrap = await get('bootstrap.sh')
+  if (!bootstrap) warn('could not fetch nextcloud-docker-dev/bootstrap.sh')
+  else if (!/update-hosts/.test(bootstrap)) {
+    fail('bootstrap.sh no longer runs scripts/update-hosts - the setup module says it adds the hostnames for you')
+  }
+
+  if ((await get('scripts/occ.sh')) === null) {
+    fail('nextcloud-docker-dev/scripts/occ.sh is gone - the course uses it throughout')
+  }
+}
+
+/** A module that tells people to pull an image that no longer exists is a wall. */
+async function checkImages() {
+  for (const image of ['nextcloud-dev-php85', 'nextcloud-dev-php83']) {
+    try {
+      const tokenRes = await fetch(`https://ghcr.io/token?scope=repository:nextcloud/${image}:pull&service=ghcr.io`, {
+        signal: AbortSignal.timeout(25_000),
+      })
+      const { token } = await tokenRes.json()
+      const res = await fetch(`https://ghcr.io/v2/nextcloud/${image}/manifests/latest`, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: 'application/vnd.oci.image.index.v1+json,application/vnd.docker.distribution.manifest.list.v2+json',
+        },
+        signal: AbortSignal.timeout(25_000),
+      })
+      if (!res.ok) fail(`container image ghcr.io/nextcloud/${image}:latest is not available (HTTP ${res.status})`)
+    } catch {
+      warn(`could not check ghcr.io/nextcloud/${image}`)
+    }
+  }
+}
+
+// ------------------------------------------------------------------- run ---
+
+checkPin()
+checkVariablesAreKnown()
+checkPinIsNotHardcoded()
+checkStandaloneFilesExist()
+listReleaseSpecificClaims()
+
+if (ONLINE) {
+  await checkLinks()
+  await checkPinAgainstDocs()
+  await checkDockerDev()
+  await checkImages()
+}
+
+const heading = ONLINE ? 'online' : 'offline'
+console.log(`\ncourse content verification (${heading}) - target Nextcloud ${PIN}\n`)
+if (notes.length) console.log(notes.map((n) => `  ${n}`).join('\n') + '\n')
+if (warnings.length) console.log('WARNINGS\n' + warnings.map((w) => `  ! ${w}`).join('\n') + '\n')
+if (failures.length) console.log('FAILURES\n' + failures.map((f) => `  x ${f}`).join('\n') + '\n')
+console.log(`${failures.length} failure(s), ${warnings.length} warning(s)`)
+process.exit(failures.length ? 1 : 0)