Skip to content

fix(export): every generated app was born declaring AGPL, not EUPL-1.2 - #135

Merged
rubenvdlinde merged 1 commit into
developmentfrom
chore/refresh-template-snapshot-eupl
Aug 5, 2026
Merged

rubenvdlinde merged 1 commit into
developmentfrom
chore/refresh-template-snapshot-eupl

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

What was broken

lib/Resources/template/appinfo/info.xml shipped <licence>agpl</licence> while the same file's description read "Free and open source under the EUPL-1.2 license." That is the scaffold the exporter copies verbatim, so every app OpenBuild has ever generated was born declaring AGPL — a licence the fleet does not use, right after a sweep corrected 829 such declarations across 19,200 files.

Proof it was live, not theoretical — a real export, before the fix:

✘ Generated app declares the requested licence
  │ appinfo/info.xml must declare the licence the export requested (EUPL-1.2).
  │     <id>melding-systeem</id>
  │     ...
  │     <licence>agpl</licence>

The fix

<licence>{{license}}</licence>.

The {{license}} token was already wired end to end — ExportJobService → RunExportJob → PlaceholderResolver, defaulting to EUPL-1.2 at all three layers — and reached exactly one file, src/manifest.json. info.xml never consumed it. So this is not "hardcode the other value": a caller who picks a licence now actually gets it.

EUPL-1.2 is the schema-correct spelling, not a preference. The Nextcloud appstore's own info.xsd enumerates EUPL-1.2 as an allowed <licence> value. It does not enumerate eupl.

Test first, and shown to fail

ExporterEndToEndTest::testGeneratedAppDeclaresTheRequestedLicence() exports a real app and asserts its info.xml declares EUPL-1.2 and does not declare agpl, and that src/manifest.json / composer.json agree. It failed against the pre-fix snapshot (output above) before it was made to pass.

Nothing covered this before. The existing unresolved-placeholder assertion matches /\{\{[a-zA-Z]+\}\}/ — and a hardcoded wrong value contains no placeholder to be left unresolved.

suite before after
tests/Integration/ExporterEndToEndTest.php 2 tests, 78 assertions, exit 0 3 tests, 85 assertions, exit 0
phpunit -c phpunit.xml (full unit) 746 tests, 2342 assertions, exit 0 746 tests, 2342 assertions, exit 0
hydra-gates --base origin/development — exit 0, 58 of 63 gates reported, 7 files in scope (not a vacuous empty-scope green)

Run on PHP 8.4 in nextcloud:latest; host PHP is 8.2 and this repo requires ^8.3.


⚠️ Why this is a one-line Edit and not the whole-tree refresh docs/releasing.md prescribes

The intended fix was a snapshot refresh — .snapshot-meta.json pins upstream 7ee06aae (2026-05-11) and upstream already says EUPL-1.2, so this looked like ordinary stale-snapshot drift. It is not. The rsync in docs/releasing.md step 1 is unsafe to run as written, measured three independent ways:

  1. There is no upstream ref this tree fast-forwards from. sourceCommit 7ee06aae is not an ancestor of upstream main or development. git branch -r --contains 7ee06aae places it only on two abandoned wsl-rescue/* branches.

  2. The snapshot carries OpenBuild-only fixes upstream never received. At least 10 commits have edited individual files inside lib/Resources/template/ since it was taken — including c87d8c4e7 fix(template): the generated app could not be built at all (#39) and 12da26f01 fix(export): make exported app a Tier-4 manifest consumer (ADR-024). rsync --delete reverts both. The tree the "do not scripted-edit individual files" rule protects no longer exists; the directory is a fork.

  3. The two trees use different placeholder dialects. OpenBuild resolves {{token}}. Upstream's appinfo/info.xml uses {APP_NAME} / {APP_SUMMARY} / {APP_DESCRIPTION}. PlaceholderResolver does not know that dialect, and the unresolved-placeholder assertion matches /\{\{[a-zA-Z]+\}\}/ only — so a refreshed tree would ship literal {APP_NAME} into every generated app's info.xml and no test would fail.

What a full refresh would actually move (snapshot vs origin/development, 2026-08-05)

47 files differ. 5 paths exist only in the snapshot and --delete would remove them: src/router, src/navigation, src/views/Dashboard.vue, src/views/settings, tests/Unit. 68 exist only upstream, including:

  • Behaviour-affecting: lib/Controller/HealthController.php, MetricsController.php, PreferencesController.php; lib/Mcp/; lib/Dashboard/; lib/Service/ActionAuthService.php; lib/Repair/InitializeActions.php + lib/actions.seed.json; new <repair-steps><install> entries in info.xml. Every generated app would gain all of it.
  • src/manifest.json changes shape entirely — upstream has migrated to manifest v2 ($schema/menu/pages) with no placeholder tokens; the snapshot's is the OpenBuild-authored v1 shape carrying {{appId}}…{{license}}. This is the ADR-024 Tier-4 contract.
  • Suppression baselines: psalm-baseline.xml, phpstan-baseline.neon, .coverage-baseline — every generated app would be born with them.
  • .forgejo/ — a full CI tree for the retired Codeberg forge, which would be propagated into every future generated app.
  • playwright.config.ts, REUSE.toml, publiccode.yml, .githooks, docs/, CONTRIBUTING.md, SECURITY.md, 37 new l10n/*.json, tests/Unit → tests/unit rename.

That is a migration with product decisions in it ("what should a generated app contain?"), not a copy — and not something to land unattended. .snapshot-meta.json and docs/releasing.md now say all of this at the point of use, so the next agent does not run the rsync on the strength of the doc alone.

Also found: the control that should have caught this does not exist

docs/releasing.md describes a "CI drift check" that "diffs lib/Resources/template/ against apps-extra/nextcloud-app-template/ and warns when the snapshot is more than 90 days behind". No workflow under .github/workflows/ mentions drift or nextcloud-app-template. It was never built. That is why the snapshot sat 86 days stale shipping the wrong licence — a documented control whose absence is indistinguishable from its success. It is now marked as non-existent in the doc. Building it is blocked on the fork decision above: a drift check has no correct comparison target until it is settled whether this tree tracks upstream or owns itself.


🔴 DECISION FOR THE MAINTAINER — ADR-014 is stale and says the opposite of this PR

.claude/openspec/architecture/adr-014-licensing.md:2-3 currently reads:

  • appinfo/info.xml: MUST use <licence>agpl</licence> — Nextcloud app store does not recognise EUPL.
  • This is intentional dual-tagging, NOT a conflict. Do NOT change info.xml to eupl. Do NOT flag as review finding.

Its stated rationale is factually false. The live Nextcloud appstore schema enumerates EUPL-1.2 as an allowed <licence> value.

And it is contradicted by the fleet it governs — every one of these already declares EUPL-1.2 in info.xml, including openbuild's own: openregister, opencatalogi, openconnector, docudesk, nldesign, softwarecatalog, larpingapp, pipelinq, procest, openbuild, decidesk, portaliq (12/12 checked).

Scope of the correction — the canonical copy is hydra/openspec/architecture/adr-014-licensing.md, mirrored into 6 apps (decidesk, openbuild, pipelinq, procest, shillinq, softwarecatalog), and its stale claim is encoded in hydra-gates gate-28 (run-hydra-gates.sh ~line 2036: "per ADR-014 we accept that drift on info.xml ONLY").

Proposed replacement for lines 2-3 (not applied — this PR changes no ADR):

  • appinfo/info.xml: MUST use <licence>EUPL-1.2</licence>. The appstore schema (https://apps.nextcloud.com/schema/apps/info.xsd) enumerates EUPL-1.2; the older short code eupl is not in the enumeration and is invalid.
  • The pre-2026 agpl short code was a workaround for an appstore taxonomy that has since added EUPL. It is legacy, not intentional dual-tagging. Flag it as a review finding.

Leaving the call to you — amending an ADR that six repos and a shared gate depend on is a decision, not a cleanup.

The embedded template snapshot's appinfo/info.xml hardcoded
`<licence>agpl</licence>` while the very same file's description read "Free
and open source under the EUPL-1.2 license". Every app OpenBuild has ever
generated inherited that contradiction, and nothing failed.

The `{{license}}` token was already wired end to end — ExportJobService ->
RunExportJob -> PlaceholderResolver, defaulting to EUPL-1.2 at all three
layers — and reached exactly one file, src/manifest.json. info.xml never
consumed it. `<licence>{{license}}</licence>` closes that, and as a side
effect a caller who picks a licence now gets the licence they picked.

EUPL-1.2 is the schema-correct spelling, not a preference: the Nextcloud
appstore's own info.xsd enumerates `EUPL-1.2` as an allowed <licence> value.
It does NOT enumerate `eupl` — which is what upstream nextcloud-app-template's
`main` branch currently ships, and is separately invalid.

A test first, and shown to fail. testGeneratedAppDeclaresTheRequestedLicence()
exports a real app and asserts info.xml declares EUPL-1.2 and does not declare
agpl. Against the pre-fix snapshot it failed with the generated app's info.xml
in the message; after the one-line change all 3 integration tests and all 746
unit tests pass. Nothing in the suite covered this before: the existing
unresolved-placeholder assertion matches /\{\{[a-zA-Z]+\}\}/, and a hardcoded
wrong value contains no placeholder to be left unresolved.

Why this is a one-line Edit and not the whole-tree refresh docs/releasing.md
prescribes. The refresh is unsafe as written, measured three ways:

  1. There is no upstream ref this tree fast-forwards from. The declared
     sourceCommit 7ee06aae is not an ancestor of upstream main OR development;
     `git branch -r --contains` places it only on two abandoned wsl-rescue/*
     branches.

  2. The snapshot carries OpenBuild-only fixes upstream never received — at
     least 10 commits have edited files inside lib/Resources/template/ since,
     among them c87d8c4 "fix(template): the generated app could not be built
     at all (#39)" and 12da26f "fix(export): make exported app a Tier-4
     manifest consumer (ADR-024)". `rsync --delete` reverts both.

  3. The dialects differ. OpenBuild resolves {{token}}; upstream's info.xml
     uses {APP_NAME}/{APP_SUMMARY}/{APP_DESCRIPTION}. PlaceholderResolver does
     not know that dialect and the unresolved-placeholder assertion does not
     match it, so a refreshed tree would ship literal {APP_NAME} into every
     generated app and no test would fail.

.snapshot-meta.json and docs/releasing.md now say so at the point of use, so
the next agent does not run the rsync on the strength of the doc alone.
docs/releasing.md also now records that the "CI drift check" it describes does
not exist — no workflow mentions drift or nextcloud-app-template — which is
why the snapshot sat 86 days stale shipping the wrong licence.

.path-manifest.txt no longer lists .snapshot-meta.json: the regeneration
command in docs/releasing.md excludes it, so the checked-in manifest
disagreed with its own generator.
@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/openbuild @ 36dba19

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
test-l10n ✅
composer ✅ ✅ 101/101
npm ✅ ✅ 654/654
PHPUnit ✅
Newman ⏭️
Playwright ⏭️
Hydra gates ✅

Quality workflow — 2026-08-05 20:10 UTC

Download the full PDF report from the workflow artifacts.

@rubenvdlinde

Copy link
Copy Markdown
Contributor Author

I ran the whole-tree refresh. Here is what it actually produces.

The PR description argued the documented rsync -a --delete was unsafe. That was analysis. This is the measurement: I performed docs/releasing.md step 1 verbatim against origin/development (fc4ebf4, 2026-08-05) in a throwaway copy of this worktree, then ran the exporter against the result.

rsync -a --delete \
  --exclude node_modules --exclude vendor --exclude .git \
  ../nextcloud-app-template/ lib/Resources/template/

Step 1 deletes the snapshot's own metadata

file survived --delete?
.snapshot-meta.json NO — deleted
.path-manifest.txt NO — deleted

Step 3 then tells you to "Update lib/Resources/template/.snapshot-meta.json" — a file step 1 has already removed. The exclude list in step 1 is also shorter than the authoritative one in .snapshot-meta.json's own excludes key.

Step 2 fails outright — 0 of 8 tokens survive

docs/releasing.md step 2: "Confirm every placeholder token is still present in the files the exporter populates."

{{appId}}: 0 file(s)          {{appVersion}}:  0 file(s)
{{appNamespace}}: 0 file(s)   {{authorName}}:  0 file(s)
{{appName}}: 0 file(s)        {{authorEmail}}: 0 file(s)
{{appDescription}}: 0 file(s) {{license}}:     0 file(s)

Upstream does not carry OpenBuild's {{token}} dialect at all. It never did — the tokens were authored into the snapshot here (12da26f01), which is precisely the "fork, not a snapshot" finding.

And the generated app comes out broken

<licence> does become EUPL-1.2 — the goal is met. But this is the appinfo/info.xml of an app exported from the refreshed template:

<id>melding-systeem</id>
<name lang="en">{APP_NAME}</name>
<name lang="nl">{APP_NAME}</name>
<summary lang="en">{APP_SUMMARY}</summary>
<summary lang="nl">{APP_SUMMARY}</summary>
<description lang="en"><![CDATA[{APP_DESCRIPTION}]]></description>
<description lang="nl"><![CDATA[{APP_DESCRIPTION}]]></description>
<version>0.1.2</version>
<licence>EUPL-1.2</licence>

A generated app whose name, summary, description and version are literal upstream placeholders. <version> is the template's own 0.1.2, not the version the export asked for.

And the shipped suite does not catch it. The unresolved-placeholder assertion matches /\{\{[a-zA-Z]+\}\}/ — {APP_NAME} is single-brace and sails straight through. I had to add a throwaway assertStringNotContainsString('{APP_', ...) probe to see it. It would have shipped silently.

The suite did catch two other refresh regressions, exit 1, Tests: 3, Assertions: 49, Failures: 2:

  • Unresolved placeholder left in README.md — upstream's README carries a {{end}} token
  • src/manifest.json must declare the same licence as appinfo/info.xml — upstream has migrated src/manifest.json to manifest v2 ($schema/menu/pages), which declares no licence and carries no tokens; the OpenBuild-authored v1 manifest and its ADR-024 Tier-4 $comment are gone

So the refresh trades one wrong line for a scaffold that cannot produce a valid app. The one-line fix in this PR is what I shipped instead, and it is proven by a test that was shown to fail first.

Full accounting of what the refresh moves

Shipped snapshot vs refreshed tree:

  • 47 files differ
  • 5 paths deleted by --delete — src/router, src/navigation, src/views/Dashboard.vue, src/views/settings, tests/Unit
  • 93 paths added

Behaviour-affecting additions, every one of which would land in every generated app:

added why it matters
lib/Controller/HealthController.php, MetricsController.php, PreferencesController.php three new HTTP surfaces
lib/Mcp/, lib/Dashboard/ new subsystems
lib/Service/ActionAuthService.php, lib/Repair/InitializeActions.php, lib/actions.seed.json new authorization service + a seeding repair step, wired via new <repair-steps><install> entries
psalm-baseline.xml, phpstan-baseline.neon, .coverage-baseline every generated app born with suppression baselines
.forgejo/ a full CI tree for the retired Codeberg forge, propagated into every future app
playwright.config.ts, tests/e2e/, scripts/, .githooks/, docs/ new toolchain surface
REUSE.toml, publiccode.yml, CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, SUPPORT.md new repo-level metadata
37 new l10n/*.json be, bg, bs, ca, cs, da, de, el, es, et, fi, fr, ga, hr, hu, is, it, lb, lt, lv, mk, mt, nb, pl, pt, rm, ro, ru, sk, sl, sq, sr, sv, tr, uk, …
tests/Unit → tests/unit directory rename
<php min-version> 8.1 → 8.3 raises the floor for every generated app

Copyright check — no foreign copyright would be pulled in. Every SPDX-FileCopyrightText in the refreshed tree resolves to Conduction B.V. (2024/2026) or 2026 Nextcloud App Template Contributors. Nothing to relabel, and nothing that would have this repo claim to relicense someone else's work.

What this leaves for you

Reconciling the fork with upstream is a migration with product decisions in it — manifest v1 → v2, three new controllers, MCP, retired-forge CI, suppression baselines — plus teaching PlaceholderResolver the {APP_*} dialect and widening the placeholder assertion to catch it. That is not a copy, and not something to land unattended. .snapshot-meta.json and docs/releasing.md now carry all of the above at the point of use so the next agent does not run the rsync on the strength of the doc alone.

@rubenvdlinde
rubenvdlinde merged commit 71f63db into development Aug 5, 2026
34 checks passed
@rubenvdlinde
rubenvdlinde deleted the chore/refresh-template-snapshot-eupl branch August 14, 2026 09:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants