Plan group-scoped links and enforce coverage gates

.agents/skills/test-driven-change/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: test-driven-change
+description: Deliver observable behavior changes through a verified Red–Green–Refactor cycle. Use for new features, bug fixes, domain logic, permission changes, API behavior, data changes, and contract changes; do not use automatically for documentation-only, formatting, generated-file, or mechanical changes without testable behavior.
+---
+
+# Deliver a test-driven change
+
+## Establish the proof
+
+Before writing the test, record:
+
+- the domain invariant;
+- the observable target behavior;
+- the defect or regression the test must detect;
+- the chosen test level;
+- what the test proves and what it does not prove;
+- relevant negative and boundary cases.
+
+Choose the lowest level that proves the real contract without replacing
+observable behavior with implementation detail. Use a higher integration,
+contract, smoke, or end-to-end level when the lower level cannot exercise the
+relevant boundary truthfully. For a bug fix, make the smallest proof a
+regression test.
+
+## Red
+
+1. Write the smallest meaningful test before changing production code.
+2. Run that test and record the command, exit code, and concrete failure or
+   assertion difference.
+3. Confirm that it fails for the expected domain reason: the target behavior
+   is missing or wrong.
+4. Do not proceed to Green when:
+   - the test is immediately green and is not an explicitly justified
+     characterization test;
+   - it fails only because of infrastructure, syntax, fixture, or configuration
+     defects;
+   - it does not reach the target behavior;
+   - it checks only a mock call although observable behavior can be checked
+     meaningfully.
+
+Repair a defective test environment without adding the target production
+behavior, then repeat Red. An immediately green test can preserve known
+behavior as a characterization test, but is not evidence of a TDD Red step.
+
+## Green
+
+1. Make only the smallest production-code change needed to satisfy the test.
+2. Add no speculative abstraction or unrelated refactoring.
+3. Run the new test again.
+4. Run the relevant existing regression suite.
+
+## Cover risk-specific evidence
+
+For permission changes, verify at least:
+
+- unauthorized access is rejected;
+- authorized access succeeds;
+- a foreign or manipulated object ID grants no access and causes no data
+  change;
+- a rejected request changes no data;
+- UI visibility is never used as a substitute for server-side access control.
+
+For database or migration changes, verify at least:
+
+- fresh installation on an empty schema;
+- upgrade from at least the immediately relevant prior version;
+- preservation or correct migration of existing data;
+- required constraints and indexes exist and preserve integrity;
+- no incomplete state after failure.
+
+For shared libraries or contracts, verify:
+
+- relevant provider and consumer contract tests;
+- every affected dependent app;
+- backward compatibility or an explicitly documented break.
+
+For write operations, verify:
+
+- the return value or HTTP result;
+- the persisted state;
+- absence of unwanted side effects;
+- repeated execution when idempotency is relevant.
+
+These checks supplement applicable repository stop gates. They do not authorize
+database, permission, cross-repository, or production changes.
+
+## Refactor
+
+Refactor only after the new test and relevant regression suite are green.
+Change no domain behavior. Run the new test and relevant existing tests again
+after refactoring.
+
+## Handle non-behavioral changes and deviations
+
+For documentation-only, formatting, generated-file, or mechanical changes
+without meaningfully testable behavior, use the suitable deterministic syntax,
+contract, generation, layout, link, or structure check instead of an artificial
+TDD cycle.
+
+State and justify every deviation from the test-driven workflow. Do not treat a
+test that was never observed red as TDD evidence.
+
+## Report
+
+Include:
+
+- the protected invariant and chosen test level;
+- the initially red test and expected failure reason;
+- the minimal implementation;
+- executed focused, regression, and contract tests as applicable;
+- concrete commands, results, and exit codes;
+- remaining untested risks;
+- justified deviations.

.agents/skills/work-in-nextcloud-app/SKILL.md

@@ -52,15 +52,23 @@ Stop immediately if production systems, Git history rewriting, new production de
 
 ## Test-first and coverage
 
-- New development and bug fixes normally follow Red – Green – Refactor. Start a bug fix with a regression test and a refactoring with characterization tests. Develop domain logic, permissions, hierarchies, conflicts, and validation test-first.
+- Use the locally available sibling skill `test-driven-change` for every new feature, bug fix, domain rule, permission change, API behavior, data change, or contract change. It is the sole detailed Red–Green–Refactor workflow; this section adds only Nextcloud-app test selection and coverage requirements.
 - API changes cover success, validation failure, and typical Allow/Deny cases. Cross-app contracts have provider and consumer contract tests. Use integration/DDEV tests for migrations and repository behavior when unit tests cannot represent the real contract.
 - Develop executable UI logic test-first; additionally cover layout, accessibility, and Nextcloud integration with suitable smoke or browser checks.
-- Permitted test-first entry exceptions are time-boxed exploratory spikes, purely declarative text/metadata or trivial presentation changes, and hard-to-isolate Nextcloud integration where a broader integration test is more truthful. Discard spike code or characterize it before adoption; give declarative changes appropriate syntax, contract, layout, or visibility checks.
+- Treat a time-boxed exploratory spike or hard-to-isolate Nextcloud integration as an explicitly justified deviation. Discard spike code or characterize it before adoption; choose the truthful broader integration level when isolation would hide the real contract.
 - Use the local fast entries named by `AGENTS.md`, normally `php tests/run.php` and `node tests/run-js.mjs`; dependency-light PHP smokes run in isolated processes. Run LocalBase and every affected consumer contract/smoke suite after a LocalBase contract change.
 - In local pre-production, app tests may use shared LocalBase test helpers through relative repository paths. Add heavier packaging/autoload structure or a larger test framework only when path handling, runners, assertions, mocks, or fixtures are materially duplicated or impair readability.
 - Known overall and app coverage must not decline unnoticed. Aim for at least 85 percent line coverage for new or materially changed executable code, report PHP and JavaScript separately, and fully cover security invariants regardless of percentages. Coverage is a warning and delivery indicator, not a substitute for meaningful assertions.
 - Do not prepare a commit or release with red relevant fast tests, contract tests, security checks, coverage gates, or delivery gates.
 
+## Persistent state and migrations
+
+- Before implementing a feature that changes persistent domain objects, determine the complete state model: allowed and forbidden starting states, preconditions, target state, side effects, error states, retry or repetition behavior, and relevant concurrency conflicts.
+- Do not expose unrestricted generic setters for status changes governed by domain transition rules. Encapsulate allowed transitions in the domain model or one clearly responsible application service and cover positive, negative, and failure cases.
+- Before a database change that can encounter existing data, document the old and new schema, transformation rules, known existing-data variants, integrity conditions, transaction boundary, resumability, and rollback limits.
+- Such a database change requires at least a fresh-install test, an upgrade test from the relevant previous version with synthetic existing data, domain data- and relationship-integrity checks, handling of invalid or contradictory legacy data, and an application test on the migrated schema.
+- Never modify a published migration after the fact. Correct it with a new migration.
+
 ## DDEV, Nextcloud, and hosting safety
 
 - Prefer local PHP/Node checks and batch DDEV checks. Control the shared DDEV project only from its documented `nextcloud-dev` root when that separate Parent workspace is actually available.

.github/workflows/tests.yml

@@ -26,20 +26,44 @@ jobs:
         uses: actions/checkout@v7
         with:
           path: app
+      - name: LocalBase-Referenz bestimmen
+        id: localbase-ref
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          if git ls-remote --exit-code --heads https://github.com/Filzmann/nextcloud-localbase.git "refs/heads/$CANDIDATE_REF" >/dev/null 2>&1; then
+            echo "ref=$CANDIDATE_REF" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=main" >> "$GITHUB_OUTPUT"
+          fi
       - name: LocalBase auschecken
         uses: actions/checkout@v7
         with:
           repository: Filzmann/nextcloud-localbase
+          ref: ${{ steps.localbase-ref.outputs.ref }}
           path: localbase
       - name: PHP einrichten
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-          coverage: none
+          coverage: ${{ matrix.php-version == '8.3' && 'xdebug' || 'none' }}
           tools: none
       - name: PHP-Tests
+        if: matrix.php-version == '8.5'
         working-directory: app
         run: php tests/run.php
+      - name: PHP-Coverage-Tooling installieren
+        if: matrix.php-version == '8.3'
+        run: composer install --working-dir=localbase/tests/coverage --no-interaction --no-progress --prefer-dist
+      - name: PHP-Coverage
+        if: matrix.php-version == '8.3'
+        working-directory: app
+        run: |
+          mkdir -p "$RUNNER_TEMP/php-coverage"
+          PHP_COVERAGE_COMMAND="$GITHUB_WORKSPACE/localbase/tests/coverage/vendor/bin/phpcov" \
+          PHP_COVERAGE_OUTPUT_DIR="$RUNNER_TEMP/php-coverage" \
+          php tests/run.php
+          php "$GITHUB_WORKSPACE/localbase/tests/coverage/merge-clover.php" orgsuite "$RUNNER_TEMP/php-coverage" 100.00
 
   javascript:
     name: JavaScript
@@ -50,16 +74,35 @@ jobs:
         uses: actions/checkout@v7
         with:
           path: app
+      - name: LocalBase-Referenz bestimmen
+        id: localbase-ref
+        env:
+          CANDIDATE_REF: ${{ github.head_ref || github.ref_name }}
+        run: |
+          if git ls-remote --exit-code --heads https://github.com/Filzmann/nextcloud-localbase.git "refs/heads/$CANDIDATE_REF" >/dev/null 2>&1; then
+            echo "ref=$CANDIDATE_REF" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=main" >> "$GITHUB_OUTPUT"
+          fi
       - name: LocalBase auschecken
         uses: actions/checkout@v7
         with:
           repository: Filzmann/nextcloud-localbase
+          ref: ${{ steps.localbase-ref.outputs.ref }}
           path: localbase
       - name: Node.js einrichten
         uses: actions/setup-node@v6
         with:
           node-version: 24
           package-manager-cache: false
-      - name: JavaScript-Tests
+      - name: JavaScript-Coverage-Tooling installieren
+        run: npm ci --prefix localbase/tests/coverage --ignore-scripts
+      - name: JavaScript-Tests mit Coverage
         working-directory: app
-        run: node tests/run-js.mjs
+        run: |
+          ../localbase/tests/coverage/node_modules/.bin/c8 \
+            --all \
+            '--include=js/**/*.js' \
+            --check-coverage \
+            --lines=95.71 \
+            node tests/run-js.mjs

ROADMAP.md

@@ -10,6 +10,7 @@ Diese Datei bündelt geplante Erweiterungen und offene Produktentscheidungen. Ve
 
 ## Geplante Erweiterungen
 
+- **Externe Links im AD-Menü:** Nextcloud-Admins können im OrgSuite-Adminbereich externe Navigationsziele mit Anzeigename, HTTPS-URL, Reihenfolge und Aktivstatus anlegen, bearbeiten und entfernen. Jeder Link kann auf eine oder mehrere bestehende Nextcloud-Gruppen eingeschränkt werden; die Mitgliedschaft wird serverseitig ausgewertet und das Menü liefert angemeldeten Personen ausschließlich die für sie sichtbaren Links. Ein sichtbarer externer Link erteilt keine Rechte im Zielsystem. Eingaben werden validiert, Ausgaben sicher escaped und unsichere URL-Schemata abgelehnt. Die Umsetzung erhält Allow-/Deny-Tests für Administration und Gruppensichtbarkeit sowie Tastatur-, Fokus- und Menü-Smokes.
 - Neue Navigationsziele werden nur gemeinsam mit einer tatsächlich vorhandenen Fachapp aufgenommen.
 - Der Adminbereich wächst nur mit freigegebenen app-übergreifenden LocalBase-Verträgen; app-spezifische Einstellungen bleiben in der Fachapp.
 - OrgSuite bleibt frei von Fachdaten und fachlichen Berechtigungserweiterungen.
@@ -18,3 +19,6 @@ Diese Datei bündelt geplante Erweiterungen und offene Produktentscheidungen. Ve
 
 - Betroffene Fachapps, bevorzugtes Fallback-Ziel und Standalone-Verhalten.
 - Serverseitige Zielberechtigungen, Tastaturbedienung und Contract-Tests jeder neuen Navigation oder Adminintegration.
+- Für externe Links: Bedeutet eine leere Gruppenauswahl „für alle angemeldeten Personen“ oder soll mindestens eine Gruppe verpflichtend sein?
+- Für externe Links: Öffnen sie standardmäßig im selben Tab oder in einem neuen Tab, und wird diese Wahl je Link konfigurierbar?
+- Für externe Links: Bleibt die Funktion zunächst ausschließlich im AD-Menü oder soll derselbe Vertrag später auch das BR-Menü unterstützen?

tests/js/suite-navigation-smoke.mjs

@@ -1,4 +1,5 @@
 import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
 import vm from 'node:vm';
 
 const source = readFileSync(new URL('../../js/suite-navigation.js', import.meta.url), 'utf8');
@@ -44,7 +45,7 @@ const document = {
     addEventListener: () => {},
 };
 const window = {OC: {generateUrl: (path, params) => path.replace('{appId}', params.appId)}};
-vm.runInNewContext(source, {document, window, Object});
+vm.runInNewContext(source, {document, window, Object}, {filename: fileURLToPath(new URL('../../js/suite-navigation.js', import.meta.url))});
 
 const nav = host.children[0];
 const links = nav.children[0].children.map((item) => item.children[0]);