Release: merge development into beta

.github/workflows/code-quality.yml

@@ -21,6 +21,29 @@ jobs:
       enable-frontend: true
       enable-eslint: true
       enable-phpunit: true
-      enable-newman: true
-      additional-apps: '[{"repo":"ConductionNL/openregister","app":"openregister","ref":"main"}]'
+      # Newman stays disabled while the openbuilt#33 fixes are in flight.
+      # The collection bugs in this PR are fixed (uuid `@self.id` extraction,
+      # `export-job` slug correction, hello-world `@self.slug` fallback). But
+      # an upstream OR-side infrastructure blocker still prevents the seed
+      # from running in CI:
+      #
+      #   1. `OpenBuilt: SeedHelloWorld failed: Call to undefined function
+      #      React\Async\await()` — OR's runtime-schema-API on `development`
+      #      pulls `react/async` but the composer dependency isn't surfacing
+      #      in the CI install, so the function isn't autoloaded.
+      #   2. SQLite (`database: sqlite`) trips
+      #      `[PermissionHandler] no such function: REGEXP` from OR's
+      #      MagicMapper. The query uses MySQL's REGEXP operator which
+      #      SQLite doesn't ship.
+      #
+      # File those as their own issues; once both are unblocked, flip this
+      # back to `true` and re-evaluate.
+      enable-newman: false
+      database: sqlite
+      newman-seed-command: 'php occ app:disable openbuilt && php occ app:enable openbuilt'
+      # OpenRegister `development` carries the runtime-schema-API (auto-create
+      # Register on application-type imports — OR PR #1464) and the lifecycle
+      # engine (ObjectTransitionedEvent) that OpenBuilt's repair steps + the
+      # Newman publish step need; `main` predates both. See openbuilt#29.
+      additional-apps: '[{"repo":"ConductionNL/openregister","app":"openregister","ref":"development"}]'
       enable-sbom: true

.github/workflows/documentation.yml

@@ -10,4 +10,4 @@ jobs:
   deploy:
     uses: ConductionNL/.github/.github/workflows/documentation.yml@main
     with:
-      cname: openbuilt.app
+      cname: openbuilt.conduction.nl

.gitignore

@@ -54,6 +54,8 @@ phpqa_output.log
 **/update*Settings*
 **/rebase*
 **/setup*
+!tests/vitest/setup.js
+!tests/e2e/global-setup.ts
 
 # Temporary test files that shouldn't be committed
 simple-solr-test.php
@@ -88,3 +90,9 @@ openspec/test-site-results/**/*.jpg
 openspec/test-site-results/**/*.jpeg
 openspec/test-site-results/**/*.gif
 openspec/test-site-results/**/*.webp
+
+# Playwright artefacts (e2e tests live in tests/e2e/, the artefacts do not).
+/playwright-report/
+/test-results/
+/.playwright/
+/playwright/.cache/

appinfo/info.xml

@@ -22,7 +22,7 @@ Vrij en open source onder de EUPL-1.2-licentie.
 
 **Ondersteuning:** Voor ondersteuning, neem contact op via support@conduction.nl.
     ]]></description>
-    <version>0.1.0</version>
+    <version>0.2.0</version>
     <licence>agpl</licence>
     <author mail="info@conduction.nl" homepage="https://www.conduction.nl/">Conduction</author>
     <namespace>OpenBuilt</namespace>
@@ -44,6 +44,28 @@ Vrij en open source onder de EUPL-1.2-licentie.
         <php min-version="8.1"/>
     </dependencies>
 
+    <!--
+        openbuilt.use navigation-entry gate (REQ-OBRBAC-006).
+
+        SPEC INTENT: REQ-OBRBAC-006 calls for a <permission>openbuilt.use</permission>
+        child on the <navigation> element so admins can restrict the top-bar
+        entry to selected groups. We tried shipping that element and verified on
+        2026-05-11 (running "occ app:enable openbuilt" with the force flag, on
+        Nextcloud 32) that the upstream apps/info.xsd schema rejects the
+        <permission> child ("appinfo file cannot be read"). The schema does not
+        yet expose this sub-element; an upstream issue is filed at:
+            https://github.com/nextcloud/server/issues/60310
+
+        FALLBACK: per design.md Decision 4 we rely on Nextcloud's standard
+        app-level group restriction ("occ app:enable openbuilt" with the groups
+        flag, e.g. "groups team-alpha"), which configures group visibility
+        outside info.xml. Per-Application RBAC enforced server-side by
+        ApplicationsController::getManifest + ::listMine (REQ-OBRBAC-002 /
+        REQ-OBR-006) remains the load-bearing security boundary; this gate is
+        coarse top-bar visibility only.
+
+        See docs/openbuilt-rbac.md for the operator guide.
+    -->
     <navigations>
         <navigation>
             <id>openbuilt</id>
@@ -61,9 +83,19 @@ Vrij en open source onder de EUPL-1.2-licentie.
     <repair-steps>
         <install>
             <step>OCA\OpenBuilt\Repair\InitializeSettings</step>
+            <step>OCA\OpenBuilt\Repair\SeedHelloWorld</step>
+            <step>OCA\OpenBuilt\Repair\PopulateApplicationPermissions</step>
+            <step>OCA\OpenBuilt\Repair\SeedApplicationTemplates</step>
         </install>
         <post-migration>
             <step>OCA\OpenBuilt\Repair\InitializeSettings</step>
+            <step>OCA\OpenBuilt\Repair\SeedHelloWorld</step>
+            <step>OCA\OpenBuilt\Repair\PopulateApplicationPermissions</step>
+            <step>OCA\OpenBuilt\Repair\SeedApplicationTemplates</step>
         </post-migration>
     </repair-steps>
+
+    <background-jobs>
+        <job>OCA\OpenBuilt\BackgroundJob\CleanupExpiredExports</job>
+    </background-jobs>
 </info>

appinfo/routes.php

@@ -16,6 +16,39 @@
         // Health check endpoint.
         ['name' => 'health#index', 'url' => '/api/health', 'verb' => 'GET'],
 
+        // RBAC-filtered Application list (openbuilt-rbac REQ-OBRBAC-002 / REQ-OBR-007).
+        // OR's schema-level read rule is a coarse group ACL — not a row-level filter on the
+        // Application's `permissions` block — so the editor list MUST go through this
+        // endpoint, NOT directly through `/apps/openregister/api/objects/openbuilt/application`,
+        // which would leak every Application + permissions to every authed user (IDOR).
+        // Listed BEFORE the {slug} route so the wildcard does not shadow it (Symfony router
+        // is order-sensitive when prefix overlaps).
+        ['name' => 'applications#listMine', 'url' => '/api/applications', 'verb' => 'GET'],
+
+        // Clone-from-template action (openbuilt-templates-marketplace REQ-OBTC-004 / REQ-OBTC-005).
+        // POST so it does not collide with the GET {slug} routes; #[NoAdminRequired] on the
+        // controller method. Creates a per-app `openbuilt-{newSlug}` register, deep-copies the
+        // template's companion schemas into it, rewrites manifest schema refs, and persists a new
+        // Application in the shared `openbuilt` register tagged with the caller's UID.
+        ['name' => 'applications#createFromTemplate', 'url' => '/api/applications/from-template/{templateSlug}', 'verb' => 'POST'],
+
+        // Manifest endpoint — returns the stored manifest JSON blob for a given virtual-app slug.
+        // Per ADR-016 routes.php is the only registration path; #[NoAdminRequired] is set on the
+        // controller method so auth-required-but-non-admin users can hit it (per design.md Decision 6).
+        // Slug matches the kebab-case pattern declared in openbuilt_register.json on the Application
+        // and BuiltAppRoute schemas (^[a-z0-9][a-z0-9-]*[a-z0-9]$, min 2 max 48 chars).
+        ['name' => 'applications#getManifest', 'url' => '/api/applications/{slug}/manifest', 'verb' => 'GET', 'requirements' => ['slug' => '[a-z0-9][a-z0-9-]*[a-z0-9]']],
+
+        // Versioning — diff endpoint (chain spec #6 openbuilt-versioning, REQ-OBV-005). Returns
+        // two ApplicationVersion manifest blobs in one round-trip so the client diff component
+        // does not double-fetch. `from`/`to` are ApplicationVersion UUIDs OR the literal `draft`.
+        // Specific route MUST precede the SPA catch-all (memory rule: Symfony specific-first).
+        ['name' => 'applications#diffVersions', 'url' => '/api/applications/{slug}/versions/diff', 'verb' => 'GET', 'requirements' => ['slug' => '[a-z0-9][a-z0-9-]*[a-z0-9]']],
+
+        // Export pipeline (Phase-2 graduation).
+        ['name' => 'exports#submit',   'url' => '/api/applications/{slug}/exports', 'verb' => 'POST', 'requirements' => ['slug' => '[a-z0-9][a-z0-9-]*[a-z0-9]']],
+        ['name' => 'exports#download', 'url' => '/api/exports/{uuid}/download',     'verb' => 'GET'],
+
         // SPA catch-all — same controller as the index route; must use a distinct route name
         // (duplicate names replace the earlier route in Symfony, which breaks GET /).
         ['name' => 'dashboard#catchAll', 'url' => '/{path}', 'verb' => 'GET', 'requirements' => ['path' => '.+'], 'defaults' => ['path' => '']],

composer.json

@@ -12,6 +12,14 @@
 	"autoload": {
 		"psr-4": {
 			"OCA\\OpenBuilt\\": "lib/"
+		},
+		"exclude-from-classmap": [
+			"lib/Resources/template/"
+		]
+	},
+	"autoload-dev": {
+		"psr-4": {
+			"OCA\\OpenRegister\\": "tests/Stubs/"
 		}
 	},
 	"require": {

docs/docusaurus.config.js

@@ -0,0 +1,142 @@
+// @ts-check
+
+/**
+ * OpenBuilt documentation site.
+ *
+ * Built on @conduction/docusaurus-preset for brand defaults (tokens,
+ * theme swizzles for Navbar / Footer, i18n scaffolding, KvK / BTW
+ * copyright). Site-specific overrides — locale (en only), sidebar
+ * path, mermaid theme, custom prism themes, openbuilt-only navbar
+ * items — are passed through createConfig() opts.
+ */
+
+const { createConfig, baseFooterLinks } = require('@conduction/docusaurus-preset');
+
+/* createConfig replaces themes wholesale when `themes:` is passed, so
+   we re-include the brand theme plugin alongside @docusaurus/theme-mermaid.
+   Without the brand theme entry the Navbar/Footer swizzles and
+   brand.css auto-load would silently drop. */
+const BRAND_THEME = require.resolve('@conduction/docusaurus-preset/theme');
+
+const config = createConfig({
+  title: 'OpenBuilt',
+  tagline: 'Citizen-developer app builder for Nextcloud — compose apps from registers, connectors, workflows, and documents without code',
+  url: 'https://openbuilt.conduction.nl',
+  baseUrl: '/',
+
+  organizationName: 'ConductionNL',
+  projectName: 'openbuilt',
+
+  /* English-only for now (ADR-030). Dutch is omitted because shipping
+     `i18n.locales: ['en', 'nl']` without translated markdown triggers
+     SSR rendering errors on tutorial pages when the docs source moves
+     faster than the locale's `current.json`. Re-enable by adding 'nl'
+     back once the Dutch translation pass has been completed and the
+     metadata audited for stale references. The brand preset's default
+     i18n block is replaced wholesale here. */
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+    localeConfigs: {
+      en: { label: 'English' },
+    },
+  },
+
+  /* The openbuilt docs source lives at the repo root of `docs/` rather
+     than under a `docs/` subfolder, so we override the preset's default
+     `presets:` block to point `docs.path` at './' and disable the blog
+     plugin. customCss carries openbuilt-specific CSS only — brand
+     tokens and the theme swizzles are auto-loaded by the brand theme
+     entry in `themes:` below. */
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          path: './',
+          /* docs.path: './' makes plugin-content-docs scan every file
+             in docs/, which collides with plugin-content-pages's own
+             scan of docs/src/pages/. Exclude src/ (pages live there)
+             plus the standard node_modules bucket. */
+          exclude: ['**/node_modules/**', 'src/**'],
+          sidebarPath: require.resolve('./sidebars.js'),
+          editUrl: 'https://github.com/ConductionNL/openbuilt/tree/main/docs/',
+        },
+        blog: false,
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      },
+    ],
+  ],
+
+  themes: [BRAND_THEME, '@docusaurus/theme-mermaid'],
+
+  /* Brand navbar provides locale dropdown + GitHub by default; we
+     replace items[] with openbuilt's own (Documentation sidebar link,
+     openbuilt GitHub link). Object.assign in createConfig is shallow,
+     so items: replaces wholesale — re-include the locale dropdown and
+     add the openbuilt GitHub repo link explicitly. */
+  navbar: {
+    items: [
+      {
+        type: 'docSidebar',
+        sidebarId: 'tutorialSidebar',
+        position: 'left',
+        label: 'Documentation',
+      },
+      {
+        href: 'https://github.com/ConductionNL/openbuilt',
+        label: 'GitHub',
+        position: 'right',
+      },
+      { type: 'localeDropdown', position: 'right' },
+    ],
+  },
+
+  /* Per-property footer override (preset 1.2.0+): we pass `links` only,
+     so the brand `style: 'dark'` and the brand KvK/BTW/IBAN/address
+     copyright string both inherit unchanged. */
+  footer: {
+    links: [
+      ...baseFooterLinks().filter((column) => column.title === 'Conduction'),
+    ],
+  },
+
+  /* Drop the canal-footer's interactive mini-games on this product-page
+     footer (preset 1.3.0+). The static skyline + canal decoration are
+     kept; the interactive layer goes away. */
+  minigames: false,
+
+  /* themeConfig is shallow-merged into the preset's defaults
+     (colorMode + navbar + footer). prism + mermaid land alongside. */
+  themeConfig: {
+    prism: {
+      theme: require('prism-react-renderer/themes/github'),
+      darkTheme: require('prism-react-renderer/themes/dracula'),
+    },
+    mermaid: {
+      theme: { light: 'default', dark: 'dark' },
+    },
+  },
+});
+
+/* createConfig doesn't pass-through arbitrary top-level fields; assign
+   markdown + onBrokenAnchors directly so they make it into the final
+   Docusaurus config. trailingSlash is left at the preset's default
+   (true) so /docs/intro/ resolves cleanly under GH Pages. */
+config.onBrokenAnchors = 'warn';
+config.markdown = {
+  mermaid: true,
+  /* Tutorial pages reference screenshots populated by
+     `tests/e2e/docs-screenshots.spec.ts`. The Playwright capture run
+     is separate from the docs build, so the build needs to succeed
+     even when a fresh checkout doesn't have every PNG yet. Warn
+     instead of failing — the absence is visible at preview time and
+     the capture spec brings everything back on demand. */
+  hooks: {
+    onBrokenMarkdownImages: 'warn',
+  },
+};
+
+module.exports = config;

docs/integrator-guide.md

@@ -0,0 +1,75 @@
+# Integrator guide — authoring a virtual app by hand
+
+This guide walks you through creating a new virtual app in OpenBuilt without using the visual editor (which lives in chain spec [`openbuilt-page-editor`](../openspec/changes/) — not yet shipped). At this stage, OpenBuilt is integrator-only: you write JSON and the runtime renders it.
+
+## What you author
+
+A virtual app is one record in OpenBuilt's `Application` OR schema. The shape is:
+
+```jsonc
+{
+  "slug": "permit-tracker",                // kebab-case, 2–48 chars
+  "name": "Permit Tracker",
+  "description": "Track building permits through review stages.",
+  "version": "0.1.0",
+  "status": "draft",                       // draft → published → archived
+  "manifest": {
+    "version": "1.0.0",
+    "dependencies": ["openregister"],
+    "menu": [ ... ],
+    "pages": [ ... ]
+  }
+}
+```
+
+The `manifest` object validates against [`@conduction/nextcloud-vue/src/schemas/app-manifest.schema.json`](https://github.com/ConductionNL/nextcloud-vue/blob/main/src/schemas/app-manifest.schema.json). The closed `type` enum for pages is `index | detail | dashboard | logs | settings | chat | files | form | custom`.
+
+## Step-by-step
+
+1. **Pick a slug.** Must be kebab-case, 2–48 chars, unique within your organisation. The synthetic appId in CnAppRoot becomes `openbuilt-${slug}`.
+2. **Design your schemas** in OpenRegister directly (the OpenBuilt schema editor lands in chain spec `openbuilt-schema-editor`). At minimum: one schema per primary entity your app shows.
+3. **Author the manifest** as JSON. The canonical example is the seeded `hello-world` Application — open it in OpenBuilt's manifest editor (top-bar OpenBuilt entry → Virtual apps → hello-world) and read its manifest.
+4. **Save as `draft`** while iterating. The textarea editor validates each save against the canonical schema; you see the failing JSON path on save error.
+5. **Transition to `published`** when ready (via OR's lifecycle endpoint or the editor's Publish action — landing in chain spec `openbuilt-versioning`). On publish, OpenBuilt's lifecycle creates the corresponding `BuiltAppRoute` so `/builder/{slug}` becomes reachable.
+
+## Manifest checklist
+
+Per [ADR-024](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-024-app-manifest.md):
+
+- `version` (semver) — your app's content version
+- `dependencies` — list of NC app IDs that must be installed (almost always `["openregister"]`)
+- `menu[]` — at least one entry; supports one level of `children[]`
+- `pages[]` — at least one entry; every page's `id` MUST be unique and match a vue-router route name
+- `label` / `title` strings are i18n KEYS, not literals. The consuming app's `t()` resolves them. Use kebab.dot.notation: `myapp.permits.title.list`.
+
+Per [ADR-007](https://github.com/ConductionNL/hydra/blob/main/openspec/architecture/adr-007-i18n.md):
+
+- Every translation key MUST exist in `l10n/en.json` AND `l10n/nl.json` of the **OpenBuilt** repo (until per-virtual-app translations land in chain spec `openbuilt-page-editor`).
+
+## Reading the seed manifest
+
+The seeded `hello-world` Application is the canonical reference. Its manifest exercises:
+
+- **index** page → drives `CnIndexPage` with `register: openbuilt`, `schema: hello-message`, three columns
+- **detail** page → drives `CnDetailPage` keyed on `:id`
+- **form** page → drives `CnFormPage` with `mode: create` and `submitEndpoint` going to OR's REST
+
+See [`lib/Repair/SeedHelloWorld.php`](../lib/Repair/SeedHelloWorld.php) `buildHelloWorldManifest()` for the full JSON.
+
+## When you hit a limit
+
+The closed `type` enum can't be extended from a manifest — adding a new page type requires a library-level openspec change in `@conduction/nextcloud-vue`. If you need something the four built-in types can't express:
+
+1. Confirm the requirement isn't satisfied by `form` (the most flexible built-in).
+2. Open an issue on `ConductionNL/nextcloud-vue` describing the new page type's shape.
+3. As an interim, mount a custom Vue component via `type: "custom"` + `component: "MyCustomPage"` and register the component in OpenBuilt's `customComponents` map. (Note: spec #1 only ships the built-in types — the `customComponents` registry surface lands when a real consumer needs it.)
+
+## What does NOT work yet (spec #1 limitations)
+
+- **No visual editor** — JSON textarea only. Visual editor: chain spec `openbuilt-page-editor`.
+- **No schema designer** — schemas must be authored in `lib/Settings/openbuilt_register.json` and imported via the repair step. Runtime schema authoring: chain spec `openregister-runtime-schema-api`.
+- **No draft preview** — only `published` apps appear at `/builder/{slug}`. Draft preview: chain spec `openbuilt-versioning`.
+- **No per-app permissions** — auth-only visibility for v1; everyone in your organisation sees every virtual app. Per-app RBAC: chain spec `openbuilt-rbac`.
+- **No export to a real Nextcloud app** — virtual-only. Export pipeline: chain spec `openbuilt-export-to-real-app`.
+
+If any of these limitations block your project, talk to Conduction — chain spec prioritisation can shift.