feat: API-Endpunkte für Dateiverwaltung und Doku ergänzen

Author: skerbis

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.5.0] - 2026-03-03
+### Added
+- API-Integration für das `api` AddOn über RoutePackages (`code` und `backend/code`).
+- Neue Endpunkte für Dateiverwaltung:
+  - `GET /api/code/files` (`code/files/list`)
+  - `POST /api/code/files` (`code/files/create`)
+  - `GET /api/code/file` (`code/file/read`)
+  - `PUT/PATCH /api/code/file` (`code/file/update`)
+  - `DELETE /api/code/file` (`code/file/delete`)
+- Backend-Mirror-Routen für Session-Auth über `/api/backend/code/*`.
+- Neuer `CodeFileService` mit zentraler Logik für Browse/Create/Read/Update/Delete.
+- Erweiterte erlaubte Textformate (u.a. `csv`, `tsv`, `log`, `rst`, `toml`, `cfg`, `properties`).
+
+### Changed
+- API-Routen werden nur registriert, wenn das `api` AddOn verfügbar ist.
+- API-Dateioperationen respektieren den Schalter `enable_file_browser` und liefern bei Deaktivierung `403`.
+- README erweitert um Scope-Liste, Curl-Beispiele und Copilot-Instructions-Beispiel.
+
+### Security
+- Pfadzugriffe bleiben auf den REDAXO-Basispfad beschränkt (Traversal-Schutz via `realpath`).
+- Löschen geschützter Dateien bleibt blockiert (z.B. `.htaccess`, `index.php`, `composer.json`, `boot.php`, `install.php`).
+
 ## [1.2.1] - 2026-01-28
 ### Fixed
 - Fatal Error: `CodeApi::__construct()` neu deklariert (doppelter Konstruktor entfernt).

README.md

@@ -177,6 +177,146 @@ The Monaco Editor automatically replaces `.rex-code` textareas in:
 3. Results show filename, line number, context
 4. Click result to open file at specific line
 
+### API (api AddOn)
+When the **api** addon is installed and active, the code addon registers these endpoints automatically:
+
+**Important prerequisite:** File operations (`/api/code/files` and `/api/code/file`) only work when **Code → Settings → File-Browser aktivieren** is enabled. If disabled, the API returns `403`.
+
+- `GET /api/code/capabilities` (Bearer token scope: `code/capabilities`)
+- `GET /api/code/files` (Bearer token scope: `code/files/list`, query: `path`)
+- `POST /api/code/files` (Bearer token scope: `code/files/create`, JSON body: `path`, `name`, `type=file|folder`)
+- `GET /api/code/file` (Bearer token scope: `code/file/read`, query: `path`)
+- `PUT/PATCH /api/code/file` (Bearer token scope: `code/file/update`, JSON body: `path`, `content`)
+- `DELETE /api/code/file` (Bearer token scope: `code/file/delete`, query: `path`)
+- `GET /api/backend/code/capabilities` (Backend session/cookie auth)
+- `GET /api/backend/code/files` (Backend session/cookie auth)
+- `POST /api/backend/code/files` (Backend session/cookie auth)
+- `GET/PUT/PATCH/DELETE /api/backend/code/file` (Backend session/cookie auth)
+
+Response includes:
+- addon metadata (`addon`, `version`)
+- file browser status (`file_browser_enabled`)
+- editable file formats (`allowed_extensions`)
+- excluded directories (`excluded_directories`)
+
+`GET /api/code/files` returns the current directory entries (folders + allowed file types).
+
+`POST /api/code/files` creates a new file or folder. Example body:
+
+```json
+{
+    "path": "redaxo/src/addons/code",
+    "name": "example.csv",
+    "type": "file"
+}
+```
+
+`GET /api/code/file` returns file metadata and `content` for an allowed file.
+
+`PUT /api/code/file` updates file content. Example body:
+
+```json
+{
+    "path": "redaxo/src/addons/code/example.csv",
+    "content": "id;name\n1;Demo\n"
+}
+```
+
+`DELETE /api/code/file` deletes an allowed non-protected file.
+
+#### Curl examples (copy & paste)
+
+Note: These examples require that the file browser is enabled in the code addon settings.
+
+```bash
+BASE='https://localhost:8443'
+TOKEN='YOUR_TOKEN'
+```
+
+List directory entries:
+
+```bash
+curl -k -sS -G \
+    -H "Authorization: Bearer $TOKEN" \
+    --data-urlencode "path=redaxo/src/addons/code" \
+    "$BASE/api/code/files"
+```
+
+Create a new CSV file:
+
+```bash
+curl -k -sS -X POST \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    --data '{"path":"redaxo/src/addons/code","name":"api_demo.csv","type":"file"}' \
+    "$BASE/api/code/files"
+```
+
+Read file content:
+
+```bash
+curl -k -sS -G \
+    -H "Authorization: Bearer $TOKEN" \
+    --data-urlencode "path=redaxo/src/addons/code/api_demo.csv" \
+    "$BASE/api/code/file"
+```
+
+Update file content:
+
+```bash
+curl -k -sS -X PUT \
+    -H "Authorization: Bearer $TOKEN" \
+    -H "Content-Type: application/json" \
+    --data '{"path":"redaxo/src/addons/code/api_demo.csv","content":"id;name\n1;Demo\n"}' \
+    "$BASE/api/code/file"
+```
+
+Delete file:
+
+```bash
+curl -k -sS -X DELETE -G \
+    -H "Authorization: Bearer $TOKEN" \
+    --data-urlencode "path=redaxo/src/addons/code/api_demo.csv" \
+    "$BASE/api/code/file"
+```
+
+Required token scopes:
+
+- `code/capabilities`
+- `code/files/list`
+- `code/files/create`
+- `code/file/read`
+- `code/file/update`
+- `code/file/delete`
+
+#### Copilot instructions example
+
+Copy this block into your project-level `.github/copilot-instructions.md` if you want consistent implementation rules for this addon API:
+
+```md
+## Code AddOn API Conventions
+
+For `redaxo/src/addons/code` API routes registered into the `api` addon:
+
+- Register route packages only when the `api` addon is available:
+    - `rex_addon::get('api')->isAvailable()`
+    - `class_exists(\FriendsOfRedaxo\Api\RouteCollection::class)`
+- Keep implementation in `lib/Api/RoutePackage/Code.php` and `lib/Api/CodeFileService.php`.
+- Use `FriendsOfRedaxo\Api\RouteCollection::registerRoute(...)` with `BearerAuth` and tag `code`.
+- Provide backend mirror routes via `lib/Api/RoutePackage/Backend/Code.php`.
+- Respect code addon config flag `enable_file_browser` and return `403` if disabled.
+- Accept only file types from `FriendsOfRedaxo\Code\EditorConfig::getAllowedExtensions()`.
+- Keep directory/path restrictions inside REDAXO base path and block traversal via realpath checks.
+- Do not allow deletion of protected files (e.g. `.htaccess`, `index.php`, `composer.json`, `boot.php`, `install.php`).
+- Keep route scopes stable for token management:
+    - `code/capabilities`
+    - `code/files/list`
+    - `code/files/create`
+    - `code/file/read`
+    - `code/file/update`
+    - `code/file/delete`
+```
+
 ### Backup & Trash
 1. Navigate to **Code → Backup & Trash**
 2. **Backups tab** - restore previous file versions

assets/code-editor.js

@@ -991,8 +991,15 @@ class CodeFileBrowser {
             'sql': 'fa-database',
             'md': 'fa-file-text-o',
             'txt': 'fa-file-text-o',
+            'csv': 'fa-file-text-o',
+            'tsv': 'fa-file-text-o',
+            'log': 'fa-file-text-o',
+            'rst': 'fa-file-text-o',
             'yml': 'fa-file-code-o',
-            'yaml': 'fa-file-code-o'
+            'yaml': 'fa-file-code-o',
+            'toml': 'fa-file-code-o',
+            'cfg': 'fa-file-code-o',
+            'properties': 'fa-file-code-o'
         };
 
         return iconMap[item.extension] || 'fa-file-o';
@@ -1011,8 +1018,15 @@ class CodeFileBrowser {
             'sql': 'sql',
             'md': 'markdown',
             'txt': 'plaintext',
+            'csv': 'plaintext',
+            'tsv': 'plaintext',
+            'log': 'plaintext',
+            'rst': 'plaintext',
             'yml': 'yaml',
-            'yaml': 'yaml'
+            'yaml': 'yaml',
+            'toml': 'plaintext',
+            'cfg': 'plaintext',
+            'properties': 'plaintext'
         };
 
         return languageMap[extension] || 'plaintext';
@@ -1021,7 +1035,8 @@ class CodeFileBrowser {
     isEditableFile(extension) {
         const editableExtensions = [
             'php', 'html', 'htm', 'css', 'scss', 'less', 'js', 'json', 'xml', 'sql',
-            'md', 'txt', 'yml', 'yaml', 'ini', 'conf', 'htaccess', 'gitignore', 'env'
+            'md', 'txt', 'csv', 'tsv', 'log', 'rst', 'toml', 'cfg', 'properties',
+            'yml', 'yaml', 'ini', 'conf', 'htaccess', 'gitignore', 'env'
         ];
 
         return editableExtensions.includes(extension);

boot.php

@@ -9,6 +9,9 @@
 require_once __DIR__ . '/lib/code_api.php';
 
 use FriendsOfRedaxo\Code\CodeApi;
+use FriendsOfRedaxo\Code\Api\RoutePackage\Backend\Code as ApiBackendCodeRoutePackage;
+use FriendsOfRedaxo\Code\Api\RoutePackage\Code as ApiCodeRoutePackage;
+use FriendsOfRedaxo\Api\RouteCollection;
 
 if (rex::isBackend()) {
     $addon = rex_addon::get('code');
@@ -28,6 +31,11 @@
     rex_view::addJsFile($this->getAssetsUrl('code-editor.js') . '?t=' . (time() + 1));
 }
 
+if (rex_addon::get('api')->isAvailable() && class_exists(RouteCollection::class)) {
+    RouteCollection::registerRoutePackage(new ApiCodeRoutePackage());
+    RouteCollection::registerRoutePackage(new ApiBackendCodeRoutePackage());
+}
+
 // API Endpoints registrieren
 if (rex_get('code_api', 'bool')) {
     $action = rex_get('action', 'string');

composer.json

@@ -20,7 +20,7 @@
     "extra": {
         "redaxo": {
             "name": "code",
-            "version": "1.0.0"
+            "version": "1.5.0"
         }
     },
     "replace": {

lang/de_de.lang

@@ -90,3 +90,5 @@ file_browser_security_point_4 = Nicht für Produktivsysteme empfohlen
 file_browser_security_point_5 = Deaktiviert sich automatisch nach 2 Tagen ohne Nutzung
 file_browser_activate_button = File-Browser aktivieren (2 Tage)
 file_browser_activate_help = Nach Aktivierung kann der File-Browser in den <a href="index.php?page=code/settings">Einstellungen</a> konfiguriert werden.
+
+api_openapi_tag_code_description = Endpunkte des Code-AddOns

lang/en_gb.lang

@@ -30,6 +30,8 @@ code_file_restored = File restored
 code_trash_emptied = Trash emptied
 code_confirm_delete = Really delete?
 code_confirm_empty_trash = Really empty trash?
+
+api_openapi_tag_code_description = Endpoints of the code addon
 code_unsaved_changes = There are unsaved changes. Continue anyway?
 code_create_file = Create new file
 code_create_folder = Create new folder