|
| 1 | +# AI Agent Guidelines for Collabora Online (richdocuments) |
| 2 | + |
| 3 | +This file provides context for AI coding agents (Claude Code, GitHub Copilot, Cursor, etc.) working in this repository. |
| 4 | + |
| 5 | +## Repository Overview |
| 6 | + |
| 7 | +`richdocuments` is the ownCloud Server app that integrates Collabora Online for real-time |
| 8 | +collaborative editing of documents, spreadsheets and presentations. ownCloud acts as the WOPI host; |
| 9 | +Collabora Online is the WOPI client. The app ships in two flavours: a classic server-rendered |
| 10 | +frontend and a connector for ownCloud Web. |
| 11 | + |
| 12 | +- **Product family:** Classic (ownCloud Server) |
| 13 | +- **Supported server versions:** `master` targets ownCloud 11 with PHP 8.3; branch `4.2` targets ownCloud 10.11+ with PHP 7.4 (see `appinfo/info.xml`) |
| 14 | +- **Primary language(s):** PHP, TypeScript/Vue, JavaScript |
| 15 | +- **Build system:** Composer, Make, pnpm + Vite |
| 16 | +- **Test framework:** PHPUnit (unit), Behat (webUI acceptance) |
| 17 | +- **CI system:** GitHub Actions |
| 18 | +- **License:** AGPL-3.0 |
| 19 | + |
| 20 | +## Architecture & Key Paths |
| 21 | + |
| 22 | +- `appinfo/` - App metadata and registration (`info.xml`, `routes.php`, `app.php`, `Migrations/`) |
| 23 | +- `lib/` - PHP backend: `Controller/` (WOPI, document, settings, federation endpoints), `Db/` (WOPI token storage), `Panels/` (admin and personal settings), `BackgroundJob/` (expired WOPI token cleanup), plus the `DiscoveryService`, `DocumentService`, `FederationService` and `FileService` classes |
| 24 | +- `src/` - Vue/TypeScript source of the ownCloud Web connector (`index.ts`, `editor.vue`), built with `@ownclouders/extension-sdk` |
| 25 | +- `js/` - Classic frontend JavaScript, hand-written (`documents.js`, `settings-admin.js`, `settings-personal.js`, `viewer/`). `js/web/richdocuments.js` is the committed Vite build output of `src/` - do not edit it by hand |
| 26 | +- `css/` - Stylesheets |
| 27 | +- `templates/` - Server-side PHP templates |
| 28 | +- `assets/` - Empty office document templates used when creating new files |
| 29 | +- `img/` - App icons and images |
| 30 | +- `l10n/` - Translations |
| 31 | +- `tests/` - PHPUnit and acceptance tests (`tests/unit/`, `tests/acceptance/`) |
| 32 | +- `admin.php` / `settings.php` - Settings entry points |
| 33 | +- `Makefile` - Build and test automation |
| 34 | +- `composer.json` - PHP dependencies |
| 35 | +- `package.json` - JavaScript dependencies |
| 36 | +- `vite.config.ts` - Vite build configuration for the Web connector |
| 37 | +- `phpunit.xml` - PHPUnit configuration (single `unit` test suite) |
| 38 | +- `phpcs.xml` - PHP_CodeSniffer configuration |
| 39 | +- `.php-cs-fixer.dist.php` - php-cs-fixer configuration |
| 40 | +- `phpstan.neon` - PHPStan configuration |
| 41 | +- `.phan/` - Phan static analysis configuration |
| 42 | +- `sonar-project.properties` - SonarCloud configuration |
| 43 | +- `vendor-bin/` - Isolated tool dependencies (phpunit, php-cs-fixer, phpcs, phan, phpstan, behat) |
| 44 | + |
| 45 | +## Development Conventions |
| 46 | + |
| 47 | +- **Branching:** `master` for the ownCloud 11 line, `4.2` for the ownCloud 10.x line. Fixes that apply to both need a PR per branch. |
| 48 | +- **Commit messages:** DCO sign-off required (`git commit -s`). Must follow [Conventional Commits](https://www.conventionalcommits.org/) format - enforced by CI via `owncloud/reusable-workflows/.github/workflows/semantic-git-message.yml`. The repository squash-merges and takes the PR title as the commit subject, so the PR title must follow the same format. |
| 49 | +- **Code style:** php-cs-fixer with the ownCloud coding standard, plus PHP_CodeSniffer (`phpcs.xml`) for the backend; ESLint and Prettier for the frontend. |
| 50 | +- **Static analysis:** Phan and PHPStan. |
| 51 | +- **PR process:** Open a PR against the target branch. All CI checks must pass. |
| 52 | +- **Quality gate:** SonarCloud analyses the repository. |
| 53 | + |
| 54 | +## Build & Test Commands |
| 55 | + |
| 56 | +```bash |
| 57 | +# Show all available targets |
| 58 | +make help |
| 59 | + |
| 60 | +# Build distribution tarball |
| 61 | +make dist |
| 62 | + |
| 63 | +# Install PHP dependencies |
| 64 | +composer install |
| 65 | + |
| 66 | +# Build the ownCloud Web connector (src/ -> js/web/) |
| 67 | +pnpm install |
| 68 | +pnpm build |
| 69 | + |
| 70 | +# Test (PHPUnit) |
| 71 | +make test-php-unit |
| 72 | + |
| 73 | +# Test (WebUI Acceptance) |
| 74 | +make test-acceptance-webui |
| 75 | + |
| 76 | +# Lint (PHP code style) |
| 77 | +make test-php-style |
| 78 | + |
| 79 | +# Fix code style |
| 80 | +make test-php-style-fix |
| 81 | + |
| 82 | +# Lint (JavaScript/TypeScript) |
| 83 | +pnpm lint |
| 84 | + |
| 85 | +# Static analysis |
| 86 | +make test-php-phan |
| 87 | +make test-php-phpstan |
| 88 | + |
| 89 | +# Clean build artifacts and dependencies |
| 90 | +make clean |
| 91 | +``` |
| 92 | + |
| 93 | +## Important Constraints |
| 94 | + |
| 95 | +- **Tests need a core checkout:** `make test-php-unit` resolves PHPUnit at `../../lib/composer/bin/phpunit`, so the app must be checked out as `apps/richdocuments` inside an ownCloud Server tree. It cannot be run from a standalone clone. |
| 96 | +- **`make appstore` is release-only:** it unconditionally calls `occ integrity:sign-app` and needs a signing key and certificate in `~/.owncloud/certificates/`. Use `make dist` for a local build; `make dist` skips signing when no certificate is present. |
| 97 | +- **WOPI dependency:** Requires a running Collabora Online server that the ownCloud server can reach, and that can reach the ownCloud server in turn. |
| 98 | +- **Dual frontend:** Has both a classic frontend (`js/`) and an ownCloud Web connector (`src/`, built with Vite into `js/web/`). Frontend changes usually need to be made in both places. |
| 99 | +- **Generated frontend bundle is committed:** regenerate `js/web/richdocuments.js` with `pnpm build` and commit the result; never hand-edit it. |
| 100 | +- **License:** AGPL-3.0, as declared in `appinfo/info.xml` and in the header of every source file. All contributions must be compatible with it. Note that this repository has no root `LICENSE`/`COPYING` file yet; adding one is tracked as OSPO follow-up work. |
| 101 | +- **Copyleft + Apache 2.0 migration:** The broader ownCloud organization is migrating repositories to Apache 2.0. AGPL-3.0 is Category X under Apache policy, so migration requires full relicensing. Do not introduce new copyleft dependencies without discussion in an issue first. |
| 102 | +- **Translations:** Must be submitted via Transifex, not as pull requests. |
| 103 | + |
| 104 | + |
| 105 | +## OSPO Policy Constraints |
| 106 | + |
| 107 | +### GitHub Actions |
| 108 | +- **Only** use actions owned by `owncloud`, created by GitHub (`actions/*`), verified on the GitHub Marketplace, or verified by the ownCloud Maintainers. |
| 109 | +- Pin all actions to their full commit SHA (not tags): `uses: actions/checkout@<SHA> # vX.Y.Z` |
| 110 | +- Never introduce actions from unverified third parties. |
| 111 | + |
| 112 | +### Dependency Management |
| 113 | +- Dependabot is configured for automated dependency updates. |
| 114 | +- Review and merge Dependabot PRs as part of regular maintenance. |
| 115 | +- Do not introduce new dependencies without discussion in an issue first. |
| 116 | + |
| 117 | +### Git Workflow |
| 118 | +- **Rebase policy**: Always rebase; never create merge commits. Use `git pull --rebase` and `git rebase` before pushing. |
| 119 | +- **Signed commits**: All commits **must** be PGP/GPG signed (`git commit -S -s`). |
| 120 | +- **DCO sign-off**: Every commit needs a `Signed-off-by` line (`git commit -s`). |
| 121 | +- **Conventional Commits & Squash Merge**: Use the [Conventional Commits](https://www.conventionalcommits.org/) format where the repository enforces it. Many repos use squash merge, where the PR title becomes the commit message on the default branch — apply Conventional Commits format to PR titles as well. A reusable GitHub Actions workflow enforces this. |
| 122 | + |
| 123 | +## Context for AI Agents |
| 124 | + |
| 125 | +- This is an ownCloud Server app (the Classic product line), not an oCIS extension. |
| 126 | +- The PHP backend implements the WOPI host side of the protocol; Collabora Online is the WOPI client. |
| 127 | +- WOPI access tokens live in the app's own `richdocuments_wopi` table (created by `appinfo/Migrations/`) and are cleaned up by the `CleanupExpiredWopiTokens` background job - be careful with their lifetime and validation when touching `lib/Controller/WopiController.php`. |
| 128 | +- Secure View (watermarking, restricted download) is gated behind an enterprise license via `ILicenseManager`, see `AppConfig::enterpriseFeaturesEnabled()`. Its acceptance coverage lives in `tests/acceptance/features/webUISecureView/`, which is the only acceptance suite in this repo - `make test-acceptance-api` exists but has no features to run here. |
| 129 | +- Runtime configuration is done via `occ config:app:set richdocuments <key> --value <value>`; see `lib/AppConfig.php` for the supported keys. |
| 130 | +- Match existing code style, keep PRs focused, and do not refactor unrelated code in the same PR. |
| 131 | +- Write tests for new functionality. |
0 commit comments