feat: migrate scholiq from Vue 2 to Vue 3 (@conduction/nextcloud-vue 2.1.0-vue3.13) (#249)

* test(e2e): make the target instance explicit — never fall back to the shared :8080 container

The suite resolved its target three different ways, all defaulting to
`http://localhost:8080` — the SHARED developer container, which bind-mounts
real host checkouts:

  * playwright.config.ts     baseURL
  * tests/e2e/global-setup.ts  login + OR_BASE_URL for the seed
  * tests/e2e/seed-example-data.mjs

and four specs in tests/e2e/spec-coverage/nextcloud-app.spec.ts built ABSOLUTE
`http://localhost:8080/...` request URLs that ignored `baseURL` entirely — two
of them WRITES (POST /api/settings, PUT /api/notification-preferences). Running
`npm run test:e2e` without setting PW_BASE_URL therefore fired admin logins, a
register import, an example-data seed and two config writes into somebody
else's working environment, and reported the results as the branch under test.

Centralise on tests/e2e/base-url.ts: strict (no localhost fallback — an unset
target is a hard error) but accepting PLAYWRIGHT_BASE_URL, the shared CI
quality workflow's BASE_URL, and this repo's historical PW_BASE_URL, so neither
a local run nor a CI run silently retargets.

* wip(scholiq): preserve in-flight Vue 3 migration after host reset

Committed mid-flight so the work survives. NOT verified: the build/deploy/e2e
run was still queued on the shared heavy-lock when the host was reset.
See the branch's PR (if any) for what remains.

* revert(docs): restore the 52 tutorial screenshots the e2e run rewrote

`npm run test:e2e` reshoots and overwrites every PNG under
docs/static/screenshots/tutorials/ as a side effect, because the
`docs-capture` Playwright project was documented as opt-in but was not: a
project listed in `projects[]` runs whenever no `--project` filter is given,
and `test:e2e` gives none.

The config is fixed on this branch (the project is now gated on
SCHOLIQ_DOCS_CAPTURE=1). These 52 binary rewrites were incidental output from
the measurement runs, not an intended docs update, so they are restored to
their `development` content and do not belong in this PR.

Also drops the untracked .scholiq-boot-smoke.mjs probe that was swept into the
preservation commit — it is a local measurement tool, not app code.

* style(php): clear the remaining 23 PHPCS errors so the gate can go green

`PHP Quality (phpcs)` has been failing on `development` for a long time — 26
errors across 11 files. It is not a cosmetic red: the shared quality workflow
gates `phpunit` on `needs.php-quality.result != 'failure'`, so scholiq's PHPUnit
suite has NEVER executed on a pull request.

An earlier commit on this branch fixed 3 of them in GradeFormulaEvaluator.php.
That number came from reading the CI log through `tail -20`, which silently cut
off every earlier file — the truncating filter decided the count. The full
inventory is 26, and this commit clears the other 23:

  8  lib/Listener/BsaProgressFlagHandler.php    const + assignment alignment,
                                                @PARAM type padding
  5  lib/Lifecycle/BsaDecisionGuard.php         const + assignment alignment,
                                                doc-comment capital, 152-char line
  2  lib/Listener/FraudCaseDecisionHandler.php  assignment alignment, 152-char line
  2  lib/Lifecycle/FraudCaseBlockGuard.php      163-char line, comment capital
  1  lib/StudyProgress/BsaProgressEvaluator.php inline IF -> if/else
  1  lib/Lifecycle/FraudCaseInvalidationGuard.php  159-char line
  1  lib/Lifecycle/FraudCaseHearingGuard.php    blank line before first function
  1  lib/Lifecycle/ExemptionDecisionGuard.php   blank line before first function
  1  lib/Lifecycle/BsaWarningSigningGuard.php   blank line before first function
  1  lib/Lifecycle/FraudCaseDecisionGuard.php   assignment alignment

All behaviour-preserving: whitespace, comment capitalisation, long log strings
split across two concatenated lines, one ternary expanded to if/else, and two
long expressions extracted to a local variable. Every touched file passes
`php -l` (positive-controlled against a deliberately malformed file).

None of these files is touched by the Vue 3 migration; they are cleared here
because the project standard is to fix pre-existing quality issues on contact
rather than leave them.

* style(php): use single-space assignment where alignment exceeds maxPadding

The previous commit aligned `$verdict` with `$contestedGradeEntryId`, which is
the wrong direction: Generic.Formatting.MultipleStatementAlignment falls back to
requiring exactly ONE space once a group's longest variable would push the
padding past maxPadding. phpcs said so plainly — "expected 1 space but found 15
spaces" — and the original code had the same error with 14. Aligning harder made
it 15.

This is the last of the 26 PHPCS errors that were failing on `development`.

* fix(e2e): bound the networkidle wait in the docs-capture helper

`go()` called `waitForLoadState('networkidle')` with no timeout. That inherits
the test budget, so it can never REJECT — the `.catch()` next to it was dead
code, and the helper blocked until the whole test timed out.

That is the entire Vue 2 -> Vue 3 e2e delta. Measured on one instance, same
page, same session, deploying each build in turn:

  Vue 2: 90 requests, 0 still in flight after 40 s -> 'UN grading' passes 2/2 (~57 s)
  Vue 3: 93 requests, 1 still in flight after 40 s -> 'UN grading' fails 3/3 (90 s),
         and still fails when given 300 s, so it HANGS rather than being slow

The straggler is `GET /apps/openregister/api/schemas/grade-entry`, which 404s
(3 of the register's 118 schemas do not import). @conduction/nextcloud-vue's
`useObjectStore.fetchSchema` does:

    if (!response.ok) return null

without consuming or cancelling the response body, so the browser keeps the
request open indefinitely and `networkidle` becomes unreachable for the life of
the page. Reported upstream — the real fix belongs in nc-vue, not here.

Bounding the wait restores the helper's stated intent (its own comment says
"idle never fires on some pages") and matches index-pages, detail-pages, shell
and accessibility-axe-scan, which all already pass an explicit timeout. No
assertion is changed, nothing is skipped: the test now PASSES on Vue 3 in 38 s.

---------

Co-authored-by: Conduction Release Bot <release-bot@conduction.nl>

Author: rubenvdlinde

.github/workflows/openspec-sync.yml

@@ -8,7 +8,16 @@ on:
 
 jobs:
   sync:
-    uses: ConductionNL/.github/.github/workflows/openspec-sync.yml@feature/openspec-project-sync
+    # ⚠️ This was pinned to `@feature/openspec-project-sync`, a branch that does
+    # not exist in ConductionNL/.github (verified with `git ls-remote --heads`,
+    # positive-controlled against `main`, which does resolve). The org is right,
+    # so a `uses:`-grep for `Conduction/` finds nothing wrong — but Actions still
+    # cannot resolve the ref, and the workflow has produced ZERO jobs on every
+    # push since 2026-05-23. The tell is in `gh run list --json name`: runs from
+    # 2026-05-18 and earlier report `OpenSpec Sync`; every run since reports the
+    # raw path `.github/workflows/openspec-sync.yml`. Pin to the default branch,
+    # as every other workflow in this repo does.
+    uses: ConductionNL/.github/.github/workflows/openspec-sync.yml@main
     with:
       app-name: scholiq
     secrets:

README.md

@@ -102,7 +102,7 @@ npm run build           # production build
 
 | Layer | Technology |
 |---|---|
-| Frontend | Vue 2.7, `@conduction/nextcloud-vue` CnAppRoot (Tier 4) |
+| Frontend | Vue 3.5, `@nextcloud/vue` 9, `@conduction/nextcloud-vue` CnAppRoot (Tier 4) |
 | Data model | `src/manifest.json` + `lib/Settings/scholiq_register.json` |
 | Build | Webpack 5, `@nextcloud/webpack-vue-config` |
 | Backend | PHP 8.1+, Nextcloud App Framework |

docs/Technical/specs.md

@@ -10,7 +10,7 @@ All 6 Wave-2 compliance-audit wedge specs have been applied. Specs live in `open
 
 **Status:** Applied
 
-**Summary:** Foundation spec that ships the standards-compliant Nextcloud app shell before any other capability can land. Delivers: `appinfo/info.xml` with hard dependencies on OpenRegister and OpenConnector; `lib/AppInfo/Application.php` registering all services and listeners; the Vue 2 SPA entry point (`src/main.js`); the admin and user settings panels; `src/manifest.json` adopting CnAppRoot Tier 4 (ADR-024); `l10n/nl.js` and `l10n/en.js` i18n stubs. All downstream specs (`course-management`, `enrolment`, `certification`, `compliance-audit`, `dashboard`) depend on this foundation.
+**Summary:** Foundation spec that ships the standards-compliant Nextcloud app shell before any other capability can land. Delivers: `appinfo/info.xml` with hard dependencies on OpenRegister and OpenConnector; `lib/AppInfo/Application.php` registering all services and listeners; the Vue 3 SPA entry point (`src/main.js`); the admin and user settings panels; `src/manifest.json` adopting CnAppRoot Tier 4 (ADR-024); `l10n/nl.js` and `l10n/en.js` i18n stubs. All downstream specs (`course-management`, `enrolment`, `certification`, `compliance-audit`, `dashboard`) depend on this foundation.
 
 ---
 

docs/features.json

@@ -8,38 +8,69 @@ const {
 	FlatCompat,
 } = require('@eslint/eslintrc')
 
+// The Vue-3 rule preset ships INSIDE @conduction/nextcloud-vue, so it can only
+// be enabled after the dependency is installed — deps first, then lint, then
+// code. `conductionVue3Fixes` is an ARRAY OF THREE configs, not one object, and
+// it registers no plugins, which is why it layers cleanly onto the @nextcloud
+// base. Spread it LAST so its overrides win.
+//
+// (CommonJS, so the extensionless subpath works. From ESM this must be
+// '@conduction/nextcloud-vue/eslint/index.js' — the package ships no `exports`
+// map, and the directory form throws ERR_UNSUPPORTED_DIR_IMPORT.)
+const { conductionVue3Fixes } = require('@conduction/nextcloud-vue/eslint')
+
 const compat = new FlatCompat({
 	baseDirectory: __dirname,
 	recommendedConfig: js.configs.recommended,
 	allConfig: js.configs.all,
 })
 
-module.exports = defineConfig([{
-	extends: compat.extends('@nextcloud'),
-
-	settings: {
-		'import/resolver': {
-			alias: {
-				map: [
-					['@', './src'],
-					['@floating-ui/dom-actual', './node_modules/@floating-ui/dom'],
-					['@conduction/nextcloud-vue', '../nextcloud-vue/src'],
-				],
-				extensions: ['.js', '.ts', '.vue', '.json', '.css'],
+module.exports = defineConfig([
+	{
+		extends: compat.extends('@nextcloud'),
+
+		settings: {
+			'import/resolver': {
+				alias: {
+					map: [
+						['@', './src'],
+						['@floating-ui/dom-actual', './node_modules/@floating-ui/dom'],
+						// Resolve the library from node_modules, NOT from the sibling
+						// `../nextcloud-vue` checkout: that checkout sits on the Vue 2
+						// (beta.*) line, so pointing the resolver at it made lint reason
+						// about a different library than the one this app builds against.
+						['@conduction/nextcloud-vue', './node_modules/@conduction/nextcloud-vue'],
+					],
+					extensions: ['.js', '.ts', '.vue', '.json', '.css'],
+				},
 			},
 		},
-	},
 
-	rules: {
-		// Allow unused i18n functions (t, n) — imported for future translation wiring
-		'no-unused-vars': ['error', { varsIgnorePattern: '^(t|n)$', argsIgnorePattern: '^_' }],
-		'jsdoc/require-jsdoc': 'off',
-		'vue/first-attribute-linebreak': 'off',
-		'@typescript-eslint/no-explicit-any': 'off',
-		'n/no-missing-import': 'off',
-		'import/namespace': 'off', // disable namespace checking to avoid parser requirement
-		'import/default': 'off', // disable default import checking to avoid parser requirement
-		'import/no-named-as-default': 'off', // disable named-as-default checking to avoid parser requirement
-		'import/no-named-as-default-member': 'off', // disable named-as-default-member checking to avoid parser requirement
+		rules: {
+			// Allow unused i18n functions (t, n) — imported for future translation wiring
+			'no-unused-vars': ['error', { varsIgnorePattern: '^(t|n)$', argsIgnorePattern: '^_' }],
+			'jsdoc/require-jsdoc': 'off',
+			// `@spec` and `@e2e` are the Hydra traceability tags (gate-16 / gate-19).
+			// They are not JSDoc-standard, so check-tag-names flagged every single
+			// use: 256 of this repo's 274 pre-existing lint warnings were this one
+			// rule complaining about a convention the quality gates REQUIRE.
+			'jsdoc/check-tag-names': ['warn', { definedTags: ['spec', 'e2e'] }],
+			'vue/first-attribute-linebreak': 'off',
+			'@typescript-eslint/no-explicit-any': 'off',
+			'n/no-missing-import': 'off',
+			'import/namespace': 'off', // disable namespace checking to avoid parser requirement
+			'import/default': 'off', // disable default import checking to avoid parser requirement
+			'import/no-named-as-default': 'off', // disable named-as-default checking to avoid parser requirement
+			'import/no-named-as-default-member': 'off', // disable named-as-default-member checking to avoid parser requirement
+		},
 	},
-}])
+
+	// MUST come last. The @nextcloud v8 base is a Vue 2 config: it activates
+	// ZERO `vue/no-deprecated-*` rules (verified with `eslint --print-config`
+	// on the pre-migration tree), so Vue-2-only idioms such as `beforeDestroy`
+	// survive a clean lint run and become silent runtime no-ops under Vue 3.
+	// It also arms two INVERTED rules — `vue/no-v-model-argument` and
+	// `vue/no-v-for-template-key`, both at severity 2 — which reject valid
+	// Vue 3 syntax. This preset fixes both directions.
+	...conductionVue3Fixes,
+])

eslint.config.js

@@ -386,7 +386,7 @@ private function compareGradedAt(array $a, array $b): int
     /**
      * Compute weighted average and breakdown from entries.
      *
-     * exam-board-case-handling: `sourceKind: exemption` entries are excluded
+     * Exam-board-case-handling: `sourceKind: exemption` entries are excluded
      * from the `$weightedSum`/`$totalWeight` accumulation (both overall and
      * per-period) — their `value` is always null and MUST NOT be cast to
      * `0.0` and summed with full weight (the pre-existing bug this fix
@@ -416,7 +416,7 @@ private function weightedAverage(array $entries, array $components): array
         foreach ($entries as $entry) {
             $cid = $entry['componentId'] ?? '';
 
-            // exam-board-case-handling: an exemption entry has no numeric value —
+            // Exam-board-case-handling: an exemption entry has no numeric value —
             // it satisfies its component without contributing to the weighted sum.
             if (($entry['sourceKind'] ?? null) === 'exemption') {
                 $componentBreakdown[$cid] = ['exempt' => true];
@@ -529,7 +529,7 @@ private function evaluatePassed(
                     return false;
                 }
             }
-        }
+        }//end if
 
         return true;
 

lib/Grading/GradeFormulaEvaluator.php

@@ -52,11 +52,11 @@
 class BsaDecisionGuard
 {
 
-    private const SCHOLIQ_REGISTER = 'scholiq';
+    private const SCHOLIQ_REGISTER   = 'scholiq';
     private const BSA_WARNING_SCHEMA = 'bsa-warning';
 
     /**
-     * decisionType values that trigger the warning + rationale requirement.
+     * DecisionType values that trigger the warning + rationale requirement.
      *
      * @var string[]
      */
@@ -114,11 +114,18 @@ public function check(array &$transitionContext): bool
         $isNegative = in_array($decisionType, self::NEGATIVE_DECISION_TYPES, true);
 
         if ($isNegative === true) {
-            $learnerId   = $object['learnerId'] ?? '';
-            $programmeId = $object['programmeId'] ?? '';
+            $learnerId    = $object['learnerId'] ?? '';
+            $programmeId  = $object['programmeId'] ?? '';
             $academicYear = $object['academicYear'] ?? '';
 
-            if ($this->hasIssuedWarning(learnerId: $learnerId, programmeId: $programmeId, academicYear: $academicYear, tenantId: $tenantId) === false) {
+            $hasWarning = $this->hasIssuedWarning(
+                learnerId: $learnerId,
+                programmeId: $programmeId,
+                academicYear: $academicYear,
+                tenantId: $tenantId
+            );
+
+            if ($hasWarning === false) {
                 $this->logger->info(
                     'BsaDecisionGuard: no issued BsaWarning found for learner {l}, programme {p}, year {y} — blocking negative decision.',
                     ['l' => $learnerId, 'p' => $programmeId, 'y' => $academicYear]

lib/Lifecycle/BsaDecisionGuard.php

@@ -63,7 +63,6 @@
  */
 class BsaWarningSigningGuard
 {
-
     /**
      * Constructor.
      *

lib/Lifecycle/BsaWarningSigningGuard.php

@@ -51,7 +51,6 @@
  */
 class ExemptionDecisionGuard
 {
-
     /**
      * Constructor.
      *

lib/Lifecycle/ExemptionDecisionGuard.php

@@ -125,13 +125,14 @@ public function check(array &$transitionContext): bool
 
         if ($lifecycle === 'decided' && $verdict === 'fraud-proven') {
             $this->logger->info(
-                '[FraudCaseBlockGuard] GradeEntry {id} permanently blocked — linked FraudCase {caseId} decided fraud-proven; the only forward path is invalidate.',
+                '[FraudCaseBlockGuard] GradeEntry {id} permanently blocked — linked FraudCase {caseId} '
+                .'decided fraud-proven; the only forward path is invalidate.',
                 ['id' => $entryId, 'caseId' => $fraudCaseId]
             );
             return false;
         }
 
-        // decided/unfounded or dismissed — publication may proceed.
+        // Decided/unfounded or dismissed — publication may proceed.
         return true;
 
     }//end check()