@jahia/agentic 0.3.0 → 0.4.1

package/dist/gemini/.agents/skills/jahia-dev-java/references/ui-extensions.md

@@ -1,344 +0,0 @@
-# Jahia UI Extensions Reference
-
-## Table of Contents
-1. [Overview: two extension layers](#1-overview-two-extension-layers)
-2. [Component registry](#2-component-registry)
-3. [Content Editor JSON overrides](#3-content-editor-json-overrides)
-4. [jContent UI extension points](#4-jcontent-ui-extension-points)
-5. [Adding UI actions](#5-adding-ui-actions)
-6. [Adding settings pages (admin routes)](#6-adding-settings-pages-admin-routes)
-7. [Custom selector types](#7-custom-selector-types)
-8. [Custom picker configuration](#8-custom-picker-configuration)
-9. [Dynamic forms in Content Editor](#9-dynamic-forms-in-content-editor)
-10. [CKEditor customization](#10-ckeditor-customization)
-11. [Debugging JSON overrides and registry](#11-debugging-json-overrides-and-registry)
-
----
-
-## 1. Overview: two extension layers
-
-| Mechanism | What it controls | Format |
-|-----------|-----------------|--------|
-| **Content Editor JSON overrides** | Form layout, field visibility, labels, sections, field order | JSON files in module JAR |
-| **Component registry** | Actions, accordions, nav items, selectors, routes, settings pages | JavaScript (React/JSX) |
-
-The component registry lives in the JavaScript layer. JSON overrides live in the Java module under `META-INF/jahia-content-editor-forms/`.
-
----
-
-## 2. Component registry
-
-```javascript
-import { registry } from '@jahia/ui-extender';
-
-registry.add('action', 'myAction', myActionObj, {
-    targets: ['contentActions:5'],
-    label: 'myModule:myAction.label'
-});
-
-registry.addOrReplace('adminRoute', 'mySettings', {
-    targets: ['administration-sites:10'],
-    label: 'myModule:settings.label',
-    isSelectable: true,
-    iframeUrl: window.contextJsParameters.contextPath + '/cms/adminframe/default/en/settings.myPage.html'
-});
-
-const existing = registry.get('action', 'createContent');
-const allActions = registry.find({ target: 'contentActions' });
-registry.remove('action', 'myAction');
-```
-
-### Registration timing
-
-```javascript
-import { registry } from '@jahia/ui-extender';
-import register from './myModule.register';
-
-export default function () {
-    registry.add('callback', 'myModule', {
-        targets: ['jahiaApp-init:50'],
-        callback: register
-    });
-}
-```
-
-### Common registry types
-
-| Type | Purpose |
-|------|---------|
-| `action` | UI action in menus, headers, or toolbars |
-| `selectorType` | Custom field input in Content Editor |
-| `adminRoute` | Admin panel page |
-| `route` | Custom top-level route |
-| `primary-nav-item` | Top-level navigation entry |
-| `accordionItem` | Secondary navigation accordion in jContent |
-| `callback` | Initialization callback |
-
----
-
-## 3. Content Editor JSON overrides
-
-### File location
-
-```
-src/main/resources/META-INF/jahia-content-editor-forms/
-    forms/          # Form-level overrides (by nodetype)
-    fieldsets/      # Fieldset-level overrides (by mixin or type)
-```
-
-Naming convention: replace `:` with `_` — `jnt:article` → `jnt_article.json`
-
-### Form override structure
-
-```json
-{
-  "nodeType": "myns:myContent",
-  "priority": 2.0,
-  "hasPreview": true,
-  "sections": [
-    {
-      "name": "content",
-      "fieldSets": [
-        {
-          "name": "<main>",
-          "rank": 1.0,
-          "fields": [
-            {
-              "name": "jcr:title",
-              "declaringNodeType": "mix:title",
-              "rank": 1.0,
-              "labelKey": "myModule:label.title"
-            },
-            {
-              "name": "myProp",
-              "hide": false,
-              "mandatory": true
-            }
-          ]
-        }
-      ]
-    },
-    { "name": "classification", "hide": true },
-    { "name": "layout", "hide": true }
-  ]
-}
-```
-
-### Key override actions
-
-| Goal | JSON |
-|------|------|
-| Hide a section | `{"name": "layout", "hide": true}` |
-| Hide a field | In field: `"hide": true` |
-| Make a field mandatory | In field: `"mandatory": true` |
-| Reorder a field | In field: `"rank": 3.0` |
-| Change a field label | In field: `"labelKey": "basename:myKey"` |
-
-### `declaringNodeType` requirement
-
-Use when the field comes from a mixin or parent type:
-
-```json
-{
-  "name": "j:invalidLanguages",
-  "declaringNodeType": "jmix:i18n",
-  "hide": false
-}
-```
-
-### Known limitations
-
-- `multiple` and `i18n` properties CANNOT be overridden by JSON
-- `valueConstraints` for choicelists can only remove existing items, not add new ones
-
----
-
-## 4. jContent UI extension points
-
-### Adding an accordion
-
-```javascript
-const baseAccordion = registry.get('accordionItem', 'pages');
-registry.add('accordionItem', 'myCustomAccordion', baseAccordion, {
-    targets: ['jcontent:99'],
-    label: 'myModule:accordion.label',
-    rootPath: '/sites/{site}/contents/my-section',
-    requiredSitePermission: 'myCustomPermission',
-    isEnabled: (siteKey) => siteKey !== 'systemsite',
-    treeConfig: Object.assign({}, baseAccordion.treeConfig, { hideRoot: false })
-});
-```
-
-**Important:** Always use `Object.assign({}, base.nestedObj, {...})` when overriding nested config objects.
-
----
-
-## 5. Adding UI actions
-
-### Available action targets
-
-| Target | Location |
-|--------|----------|
-| `contentItemContextActions` | Right-click menu on content items |
-| `contentItemActions` | Three-dot menu on content items |
-| `browseControlBar` | Three-dot menu in header |
-| `headerPrimaryActions` | Header primary action buttons |
-| `selectedContentActions` | Actions for selected content |
-| `publishMenu` | Publish dropdown menu items |
-
-### Registering an action
-
-```javascript
-registry.add('action', 'myCustomAction', {
-    buttonLabel: 'myModule:actions.myAction.label',
-    targets: ['contentItemActions:5', 'contentItemContextActions:5'],
-    showOnNodeTypes: ['jnt:article', 'jnt:page'],
-    requiredPermission: ['jcr:modifyProperties'],
-    onClick: ({ path, paths, client, notificationContext }) => {
-        console.log('Action on:', path);
-    }
-});
-```
-
----
-
-## 6. Adding settings pages (admin routes)
-
-```javascript
-registry.add('adminRoute', 'mySettings', {
-    targets: ['administration-sites:50'],
-    requiredPermission: 'adminTemplates',
-    label: 'myModule:settings.label',
-    isSelectable: true,
-    render: () => <MySettingsPage/>
-});
-```
-
-### iFrame-based admin route
-
-```javascript
-registry.add('adminRoute', 'myLegacySettings', {
-    targets: ['administration-server-systemComponents:10'],
-    requiredPermission: 'adminTemplates',
-    label: 'myModule:legacy.label',
-    isSelectable: true,
-    iframeUrl: window.contextJsParameters.contextPath +
-        '/cms/adminframe/default/$lang/settings.myLegacyPage.html?redirect=false'
-});
-```
-
-### Administration target groups
-
-| Target group | Description |
-|-------------|-------------|
-| `administration-server-usersAndRoles` | Server > Users and Roles |
-| `administration-server-systemComponents` | Server > System Components |
-| `administration-sites` | Sites section |
-
----
-
-## 7. Custom selector types
-
-```javascript
-registry.add('selectorType', 'MyColorPicker', {
-    targets: ['BuiltInTypes:10'],
-    cmp: MyColorPickerComponent,
-    supportedTypes: ['String'],
-});
-```
-
-Reference in CND:
-```cnd
-- myColor (string, MyColorPicker)
-```
-
----
-
-## 8. Custom picker configuration
-
-```javascript
-registry.add('pickerConfig', 'myPicker', {
-    accordionItem: 'pages',
-    searchSelectorType: ['jnt:article', 'jnt:page'],
-    selectableTypes: ['jnt:article'],
-    openableTypes: ['jnt:page', 'jnt:contentFolder']
-});
-```
-
-Reference in CND:
-```cnd
-- relatedArticle (weakreference, picker[type='myPicker'])
-```
-
----
-
-## 9. Dynamic forms in Content Editor
-
-Implement `DynamicFieldSetExtractor` for server-side dynamic forms:
-
-```java
-@Component(service = DynamicFieldSetExtractor.class)
-public class MyDynamicExtractor implements DynamicFieldSetExtractor {
-
-    @Override
-    public Set<String> getExtendedNodeTypesToFill(JCRNodeWrapper node,
-            ExtendedNodeType primaryNodeType, Locale locale, RenderContext ctx) {
-        String category = node.getPropertyAsString("myCategory");
-        if ("premium".equals(category)) {
-            return Collections.singleton("myns:premiumFields");
-        }
-        return Collections.emptySet();
-    }
-}
-```
-
----
-
-## 10. CKEditor customization
-
-### CKEditor 5 (Jahia 8.2+)
-
-```javascript
-registry.add('ckeditor5Plugin', 'myPlugin', {
-    plugin: MyCKEditorPlugin,
-    config: { toolbar: { items: ['myButton'] } }
-});
-```
-
-### CKEditor 4 (legacy)
-
-Place custom configuration in `src/main/resources/javascript/ckeditor/config.js`.
-
----
-
-## 11. Debugging JSON overrides and registry
-
-### Checking JSON override registration
-
-Look in Jahia startup logs for `StaticDefinitionsRegistry` entries:
-```
-INFO  [StaticDefinitionsRegistry] - Successfully loaded static form for name myns:myContent
-```
-
-### Querying the generated form via GraphQL
-
-```graphql
-{
-  forms {
-    editForm(uiLocale: "en", locale: "en", uuidOrPath: "/sites/mySite/home/myContent") {
-      sections {
-        name
-        fieldSets { name fields { name selectorType mandatory hide } }
-      }
-    }
-  }
-}
-```
-
-### Inspecting the component registry in browser console
-
-```javascript
-window.jahia.uiExtender.registry.find({ type: 'action' });
-window.jahia.uiExtender.registry.get('accordionItem', 'pages');
-window.jahia.uiExtender.registry.find({ target: 'contentItemActions' });
-```

package/dist/gemini/.agents/skills/jahia-dev-osgi-module/SKILL.md

@@ -1,297 +0,0 @@
----
-name: jahia-dev-osgi-module
-description: Conventions and invariants for building any Jahia OSGi/Java bundle module (Jahia 8.2). Use when working on Maven bundle structure, OSGi Declarative Services, JCR integration, or Java package design.
----
-
-# SKILL — Jahia OSGi Module Development (8.2)
-
-## When this skill applies
-
-You are working on anything that touches the OSGi bundle structure, Maven build, JCR node-type definitions, or Jahia service integration. That is, almost every Java change in a Jahia module.
-
-## Scaffold a new module
-
-Use the official Maven archetype. Always pick archetype **2** (`jahia-module-archetype`) and the latest version.
-
-```bash
-mvn archetype:generate -Dfilter=org.jahia.archetypes:
-```
-
-At the interactive prompts:
-1. Enter `2` → `jahia-module-archetype` (Jahia DXP >=8)
-2. Enter the latest version number (currently `4.8`)
-3. Fill in the properties below, then confirm with `Y`
-
-| Property | Example | Notes |
-|---|---|---|
-| `artifactId` | `my-module` | Maven artifact ID and folder name |
-| `moduleName` | `My Module` | Human-readable name shown in Jahia UI |
-| `groupId` | `org.example.modules` | Java package root |
-| `jahiaVersion` | `8.2.0.0` | Target Jahia version — use `8.2.0.0`, not the archetype default |
-| `version` | `1.0.0-SNAPSHOT` | Module version |
-| `package` | `org.example.modules` | Java package (usually matches `groupId`) |
-
-> ⚠️ **Always set `jahiaVersion` to `8.2.0.0`** — the archetype default (`8.0.0.0`) is outdated. The parent POM version in the generated `pom.xml` should be `org.jahia.modules:jahia-modules:8.2.0.0`. If the archetype sets a different version, update it before your first build.
-
-After generation, the scaffolded structure contains:
-```
-<artifactId>/
-├── pom.xml
-└── src/
-    ├── main/
-    │   ├── java/<package>/       # Java sources
-    │   └── resources/
-    │       └── META-INF/
-    │           └── definitions.cnd   # Empty — add your node types here
-    └── test/
-        └── java/<package>/
-```
-
-Build immediately to verify the scaffold compiles:
-
-```bash
-cd <artifactId>
-mvn clean install
-```
-
----
-
-## Hard invariants
-
-1. **Parent POM is `org.jahia.modules:jahia-modules:8.2.0.0`.** Do not bump without a documented decision. This version constrains the Java baseline (Java 17 max), the OSGi spec level (R6 / `osgi.cmpn` 6.0.0), and the available platform APIs.
-
-2. **Packaging is `bundle`.** The manifest is generated by `maven-bundle-plugin` (BND) configured in the parent. The parent already sets `Jahia-Module-Type`, `Bundle-Category`, signature, SCM headers, and default JDK target — **do not redeclare them**. Use `<jahia-depends>` and `<jahia-module-signature>` properties to drive the inherited config.
-
-3. **Dependencies on Jahia APIs go through `org.jahia.server:jahia-impl` and `jahia-api`** (both `provided`). On `jahia-impl`, exclude transitives:
-   ```xml
-   <exclusions>
-     <exclusion><groupId>*</groupId><artifactId>*</artifactId></exclusion>
-   </exclusions>
-   ```
-
-4. **OSGi services use Declarative Services (DS) annotations** (`@Component`, `@Reference`, `@Activate`). Enable BND processing with `<_dsannotations>*</_dsannotations>` (already set in the parent pom). Never use Blueprint; never use the `BundleActivator` pattern for new code.
-
-5. **`@Component` services that are part of the public SPI must declare a `service` attribute** (e.g. `@Component(service = MyInterface.class)`) so the registry can look them up by interface.
-
-6. **Public packages must be declared in `Export-Package`.** Internal implementation lives in `*.internal.*` packages and is *not* exported.
-
----
-
-## Directory conventions
-
-| Path | Purpose |
-|---|---|
-| `src/main/java/org/jahia/modules/<name>/` | Java sources |
-| `src/main/resources/META-INF/definitions.cnd` | JCR node type definitions |
-| `src/main/resources/javascript/apps/` | jContent UI extension entry point |
-| `src/main/resources/resources/` | i18n bundles (`.properties` files) |
-| `src/main/import/repository.xml` | Initial JCR content imported on first install |
-
----
-
-## Java baseline
-
-- Java 17. Records, sealed types, pattern matching, `var`, `switch` expressions are all fine.
-- Do **not** use Java 21-only features (virtual threads at the API surface, primitive pattern matching, etc.).
-- Prefer `java.util.Optional`, `java.time.*`, `java.util.concurrent.*` over Guava/Apache Commons unless an existing dependency already provides them.
-
----
-
-## JCR access patterns
-
-- Always run JCR mutations as the calling Jahia user:
-  ```java
-  JCRTemplate.getInstance().doExecuteWithUserSession(username, workspace, locale, callback)
-  ```
-  Never escalate to a system session for content the user authored or requested.
-- For reads where the user has implicit access, prefer receiving the `JCRSessionWrapper` from the controller layer rather than obtaining one yourself — this keeps the audit trail clean.
-- Save changes explicitly (`session.save()`); do not rely on auto-commit.
-- `JCRSessionWrapper` is per-user, per-workspace, per-locale, **and not thread-safe**. Never hold a reference across threads.
-- Wrap user-visible errors in domain-specific exceptions; let infrastructure exceptions (`RepositoryException`) bubble up to the caller, which converts them to the appropriate response format.
-
----
-
-## OSGi service pattern
-
-```java
-@Component(service = MyService.class, immediate = true)
-public class MyServiceImpl implements MyService {
-
-    @Reference
-    private JahiaSitesService sitesService;
-
-    @Activate
-    protected void activate(Map<String, Object> config) {
-        // initialization logic
-    }
-}
-```
-
-- `immediate = true` is needed for services that must activate on bundle start (e.g. servlet registrations, JCR event listeners).
-- Use `@Reference(cardinality = ReferenceCardinality.OPTIONAL)` for optional dependencies.
-- Constructor injection is preferred over field injection for testability.
-
----
-
-## OSGi configuration (CFG files) — avoids redeployment
-
-**Always use a `.cfg` file for any runtime-configurable property** (API keys, URLs, feature flags, timeouts, rate limits). OSGi Config Admin reloads the file at runtime without requiring a module redeploy — changes take effect immediately via the `@Modified` callback.
-
-### File location and naming
-
-```
-src/main/resources/META-INF/configurations/<service.pid>.cfg
-```
-
-The filename **must match the `service.pid`** declared on the `@Component`. Convention:
-
-```
-org.<org>.<module-name>.cfg                       # main service config
-org.jahia.modules.jahiacsrfguard-<module>.cfg     # CSRF whitelist (one per module with Actions)
-```
-
-### Main config pattern — DS `@Activate` + `@Modified` (preferred)
-
-Use the **snapshot pattern** with Declarative Services annotations. This is cleaner than implementing `ManagedService` — no need for the extra service declaration, and `@Modified` fires automatically on `.cfg` changes without a full component restart.
-
-```java
-@Component(
-    service = MyService.class,
-    configurationPid = "org.example.mymodule",   // links to the .cfg filename
-    immediate = true
-)
-public class MyServiceImpl implements MyService {
-
-    private volatile Snapshot config = Snapshot.empty();
-
-    @Activate
-    @Modified   // ← same method handles both initial activation and runtime config changes
-    protected void activate(Map<String, Object> properties) {
-        this.config = Snapshot.from(properties);
-    }
-
-    @Override
-    public String process(String input) {
-        Snapshot cfg = this.config;                // single volatile read — consistent snapshot
-        if (!cfg.isConfigured()) throw new IllegalStateException("Service not configured");
-        // use cfg.apiKey, cfg.baseUrl, cfg.timeoutMs ...
-    }
-
-    // Immutable snapshot — readers always see a complete, consistent config
-    private static final class Snapshot {
-        final String apiKey;
-        final String baseUrl;
-        final int timeoutMs;
-
-        private Snapshot(String apiKey, String baseUrl, int timeoutMs) {
-            this.apiKey = apiKey;
-            this.baseUrl = baseUrl;
-            this.timeoutMs = timeoutMs;
-        }
-
-        static Snapshot empty() { return new Snapshot("", "https://api.example.com", 30_000); }
-
-        static Snapshot from(Map<String, Object> p) {
-            return new Snapshot(
-                str(p, "API_KEY",       ""),
-                str(p, "API_BASE_URL",  "https://api.example.com"),
-                intVal(p, "TIMEOUT_MS", 30_000)
-            );
-        }
-
-        boolean isConfigured() { return !apiKey.isBlank() && !baseUrl.isBlank(); }
-
-        private static String str(Map<String, Object> m, String k, String def) {
-            Object v = m.get(k);
-            return (v instanceof String s && !s.isBlank()) ? s.trim() : def;
-        }
-        private static int intVal(Map<String, Object> m, String k, int def) {
-            try { return Integer.parseInt(String.valueOf(m.get(k))); }
-            catch (Exception e) { return def; }
-        }
-    }
-}
-```
-
-> **Why snapshot?** The `volatile Snapshot` field is replaced atomically. Callers that read `this.config` in a method always see a fully-initialized, internally consistent configuration — never a mix of old key + new URL. This is thread-safe without synchronization.
-
-> **Why `@Activate` + `@Modified` together?** OSGi DS calls `@Activate` on first start and `@Modified` when the `.cfg` file changes without stopping the component. Pointing both to the same method means a single code path handles both cases. If only `@Activate` is annotated, a config change triggers a full stop/start cycle instead of a lightweight update.
-
-### The `.cfg` file
-
-```properties
-# src/main/resources/META-INF/configurations/org.example.mymodule.cfg
-#
-# Deployed to: digital-factory-data/karaf/etc/
-# Edit that file at runtime — changes take effect without redeployment.
-#
-API_KEY=
-API_BASE_URL=https://api.example.com
-TIMEOUT_MS=30000
-```
-
-> The `.cfg` file ships with safe defaults. Operators override it in `digital-factory-data/karaf/etc/` on each environment (dev / staging / prod) — secrets never live in the source repository.
-
-### CSRF guard config (required for every module with Java Actions)
-
-```properties
-# src/main/resources/META-INF/configurations/org.jahia.modules.jahiacsrfguard-mymodule.cfg
-whitelist = *.myFirstAction.do, *.mySecondAction.do
-```
-
-One entry per Action name. Missing this file means every POST to those endpoints is rejected with 403.
-
----
-
-## GraphQL extensions
-
-- Provided by the `graphql-dxm-provider` module (declare as `<jahia-depends>`).
-- Extend by registering classes annotated with `@GraphQLTypeExtension`, `@GraphQLField`, etc.
-- Authentication is inherited from the HTTP request; resolvers run as the authenticated user.
-- Register as a `@Component(service = DXGraphQLExtensionsProvider.class)`.
-
----
-
-## Adding a dependency
-
-1. Check if Jahia already provides it via `jahia-impl` exports before adding.
-2. If available at runtime: `<scope>provided</scope>`.
-3. If it must be bundled: `Embed-Dependency` in the BND config (last resort — adds to bundle size and risks classpath conflicts).
-
----
-
-## Testing
-
-- **Unit tests:** JUnit 5 + Mockito. Place under `src/test/java`.
-- **Integration tests:** Use the `jahia-test-utils` framework against a running Jahia instance. Tag with `@Tag("integration")` and isolate from the unit test run.
-- Do not mock core Jahia services in integration tests — load them from the real OSGi registry. The registry is the contract.
-
----
-
-## Common pitfalls
-
-- ❌ Adding a dependency without checking if Jahia already provides it → check `jahia-impl` exports first.
-- ❌ `LoggerFactory.getLogger(getClass())` in a `static` context → use `LoggerFactory.getLogger(MyClass.class)`.
-- ❌ Holding `JCRSessionWrapper` references across threads → sessions are not thread-safe.
-- ❌ Forgetting to export public packages → consumers won't see the service.
-- ❌ Using `jmix:studioOnly` in CND definitions → it can silently break area rendering. Use `jmix:hiddenType`.
-- ❌ Declaring `j:linknode` or `j:url` in a CND alongside `choicelist[linkTypeInitializer]` → they are injected automatically by Jahia's mixins at runtime.
-
----
-
-## Useful Jahia service entry points
-
-```java
-JCRTemplate.getInstance().doExecuteWithUserSession(...)   // primary JCR access pattern
-JahiaSitesService.getInstance().getSiteByKey(siteKey)     // resolve a site
-JCRSessionFactory.getInstance().getCurrentUser()          // current Jahia user
-NodeTypeRegistry.getInstance().getNodeType(name)          // node type metadata
-```
-
----
-
-## References
-
-- Jahia 8 developer documentation: https://academy.jahia.com
-- Native Jahia node types (CND source): https://github.com/Jahia/jahia/tree/master/war/src/main/webapp/WEB-INF/etc/repository/nodetypes
-- Jahia GraphQL API: https://academy.jahia.com/documentation/developer/jahia/8/api-documentation/graphql-api