@jahia/agentic 0.4.0 → 0.4.1

package/dist/codex/.agents/skills/jahia-dev-java/references/modules.md

@@ -1,218 +0,0 @@
-# Jahia Java Module Development Reference
-
-## Table of Contents
-1. [Module types and structure](#1-module-types-and-structure)
-2. [Maven pom.xml patterns](#2-maven-pomxml-patterns)
-3. [Deployment methods](#3-deployment-methods)
-4. [Deploy-free coding](#4-deploy-free-coding)
-5. [Static asset management](#5-static-asset-management)
-6. [Java 11 / 17 configuration](#6-java-11--17-configuration)
-7. [OSGi tooling in Karaf](#7-osgi-tooling-in-karaf)
-8. [Troubleshooting common deployment errors](#8-troubleshooting-common-deployment-errors)
-
----
-
-## 1. Module types and structure
-
-| Type | Purpose |
-|------|---------|
-| `module` | Standard content module (default) |
-| `system` | System-level services, loaded early |
-| `templatesSet` | Provides site page templates |
-
-### Directory structure
-
-```
-src/main/
-  java/                    # Java source code
-  resources/
-    META-INF/
-      definitions.cnd      # Content type definitions
-      rules.drl            # Drools rules (all workspaces)
-      default-rules.drl    # Rules for edit/preview workspace only
-      live-rules.drl       # Rules for live workspace only
-      rules.dsl            # Custom DSL extensions
-      configurations/      # OSGi .cfg files deployed to karaf/etc/
-      patches/             # Groovy migration scripts
-    OSGI-INF/blueprint/    # Blueprint XML (deprecated in 8.2)
-  webapp/
-    css/
-    javascript/
-    icons/                 # Node type icons (jnt_news.png format)
-    resources/             # Resource bundles (ModuleName.properties)
-    WEB-INF/macros/        # Groovy/Velocity macros
-```
-
-Icons naming: replace `:` with `_` — `jnt:news` → `jnt_news.png`.
-
----
-
-## 2. Maven pom.xml patterns
-
-### Minimal pom.xml
-
-```xml
-<parent>
-  <artifactId>jahia-modules</artifactId>
-  <groupId>org.jahia.modules</groupId>
-  <version>8.2.0.0</version>
-</parent>
-
-<groupId>org.example</groupId>
-<artifactId>my-module</artifactId>
-<version>1.0.0-SNAPSHOT</version>
-<packaging>bundle</packaging>
-<name>My Module</name>
-
-<properties>
-  <jahia-depends>default,assets</jahia-depends>
-  <jahia.modules.importPackage>org.jahia.defaults.config.spring</jahia.modules.importPackage>
-  <export-package>org.example.mymodule.api</export-package>
-</properties>
-
-<build>
-  <plugins>
-    <plugin>
-      <groupId>org.apache.felix</groupId>
-      <artifactId>maven-bundle-plugin</artifactId>
-      <extensions>true</extensions>
-      <configuration>
-        <instructions>
-          <Jahia-Module-Type>module</Jahia-Module-Type>
-          <Jahia-Static-Resources>/css,/icons,/javascript</Jahia-Static-Resources>
-          <Jahia-Source-Folders>${project.basedir}</Jahia-Source-Folders>
-          <Embed-Dependency>*;scope=compile|runtime;type=!pom;inline=false</Embed-Dependency>
-          <_dsannotations>*</_dsannotations>
-        </instructions>
-      </configuration>
-    </plugin>
-    <plugin>
-      <groupId>org.jahia.server</groupId>
-      <artifactId>jahia-maven-plugin</artifactId>
-    </plugin>
-  </plugins>
-</build>
-```
-
-### Declaring module dependencies with version constraints
-
-```xml
-<jahia-depends>dep-module1=4.1,dep-module2,dep-module3=[0, 3)</jahia-depends>
-<jahia-depends>dep-module1=optional</jahia-depends>
-```
-
----
-
-## 3. Deployment methods
-
-### Method 1: Copy to modules directory (development)
-Drop the JAR into `digital-factory-data/modules/`. Jahia auto-deploys.
-
-### Method 2: Maven deploy goal (recommended)
-```xml
-<profile>
-  <id>jahia-local</id>
-  <properties>
-    <jahia.deploy.targetServerType>tomcat</jahia.deploy.targetServerType>
-    <jahia.deploy.targetServerDirectory>/path/to/jahia/apache-tomcat</jahia.deploy.targetServerDirectory>
-  </properties>
-</profile>
-```
-```bash
-mvn clean install jahia:deploy -P jahia-local
-# For Docker:
-mvn jahia:deploy -Djahia.deploy.targetContainerName=CONTAINER_NAME
-```
-
-### Creating a new module from archetype
-```bash
-mvn archetype:generate -Dfilter=org.jahia.archetypes:
-# Select: jahia-module-archetype
-```
-
----
-
-## 4. Deploy-free coding
-
-Deploy-free coding allows JSP, CSS, JS, and CND changes to be reflected without redeployment.
-
-**Requirement:** `Jahia-Source-Folders` must point to the project base directory in MANIFEST.
-
-**Limitations:** Java class changes still require redeployment. Remove `Jahia-Source-Folders` for release builds.
-
----
-
-## 5. Static asset management
-
-Assets are served from within the OSGi bundle JAR:
-```xml
-<Jahia-Static-Resources>/css,/icons,/images,/javascript</Jahia-Static-Resources>
-```
-
-OSGi configuration files shipped with a module go in:
-`src/main/resources/META-INF/configurations/` → auto-deployed to `digital-factory-data/karaf/etc/`
-
-To prevent overwriting on upgrade, start the file with:
-```
-# default configuration
-```
-
----
-
-## 6. Java 11 / 17 configuration
-
-For Java 17, add to JVM startup arguments:
-```
---add-opens java.base/java.lang=ALL-UNNAMED
---add-opens java.base/java.io=ALL-UNNAMED
---add-opens java.base/java.util=ALL-UNNAMED
-```
-
----
-
-## 7. OSGi tooling in Karaf
-
-```bash
-ssh -p 8101 jahia@localhost
-bundle:list                    # List all OSGi bundles
-jahia:modules                  # List Jahia modules with state
-bundle:requirements --namespace=osgi.wiring.package <bundleId>  # Package requirements
-jcr:query "SELECT * FROM [jnt:page]"  # Execute JCR SQL2 query
-```
-
-### Jahia Maven Plugin goals for OSGi diagnostics
-
-```bash
-mvn jahia:dependencies          # Generate/inspect Import-Package list
-mvn jahia:find-package-uses -DpackageNames=com.example.pkg
-mvn jahia:osgi-inspect          # Dump MANIFEST headers of built JAR
-```
-
----
-
-## 8. Troubleshooting common deployment errors
-
-### Bundle stuck in Installed/Resolved (not Started)
-
-Causes:
-1. Missing package import
-2. Unsatisfied Jahia-Depends
-3. CND dependency not met
-
-Diagnosis:
-```bash
-bundle:requirements --namespace=osgi.wiring.package <bundleId>
-bundle:requirements --namespace=com.jahia.services.content <bundleId>
-```
-
-### JSP compilation error: "class cannot be resolved"
-
-Solution: Add the package to `jahia.modules.importPackage` or run `mvn jahia:dependencies`.
-
-### "Unresolved constraint in bundle" on deploy
-
-```
-Unable to resolve 118.0: missing requirement [118.0] osgi.wiring.package
-```
-
-Solution: Use `mvn jahia:find-package-uses` to identify source. Mark as `resolution:=optional` if not needed at runtime.

package/dist/codex/.agents/skills/jahia-dev-java/references/osgi.md

@@ -1,208 +0,0 @@
-# Jahia OSGi Reference
-
-## Table of Contents
-1. [OSGi fundamentals](#1-osgi-fundamentals)
-2. [Jahia OSGi architecture](#2-jahia-osgi-architecture)
-3. [Declarative Services (preferred)](#3-declarative-services-preferred)
-4. [Blueprint XML (deprecated in 8.2)](#4-blueprint-xml-deprecated-in-82)
-5. [Package imports and exports](#5-package-imports-and-exports)
-6. [Embedding vs importing libraries](#6-embedding-vs-importing-libraries)
-7. [Service export between modules](#7-service-export-between-modules)
-8. [Available Jahia OSGi services](#8-available-jahia-osgi-services)
-9. [Bundle lifecycle states](#9-bundle-lifecycle-states)
-
----
-
-## 1. OSGi fundamentals
-
-Each bundle:
-- Has its own class loader (isolation)
-- Declares what packages it imports (`Import-Package`)
-- Declares what packages it exports (`Export-Package`)
-- Registers services in a shared service registry
-- Can be installed, started, updated, stopped, and uninstalled at runtime
-
----
-
-## 2. Jahia OSGi architecture
-
-```
-Jahia Application (DX)
-  └── Apache Karaf         (module management, clustering support, SSH shell)
-        └── Apache Felix   (OSGi framework implementation)
-              └── Tomcat   (servlet container)
-```
-
----
-
-## 3. Declarative Services (preferred)
-
-Declarative Services (DS) is the **only recommended** way to register OSGi services in Jahia 8.2.
-
-### Enable DS annotation scanning in pom.xml
-```xml
-<_dsannotations>*</_dsannotations>
-```
-
-### Component declaration
-
-```java
-@Component(service = {MyServiceInterface.class})
-public class MyServiceImpl implements MyServiceInterface {
-
-    @Activate
-    public void activate(BundleContext context) { }
-
-    @Deactivate
-    public void deactivate() { }
-}
-```
-
-### Referencing a single service
-
-```java
-@Reference
-public void setDependency(MyDependency dep) { this.dep = dep; }
-
-public void unsetDependency(MyDependency dep) { this.dep = null; }
-```
-
-### Referencing multiple services
-
-```java
-@Reference(cardinality = ReferenceCardinality.MULTIPLE,
-           policy = ReferencePolicy.DYNAMIC,
-           policyOption = ReferencePolicyOption.GREEDY)
-public synchronized void addService(MyService service) { this.services.add(service); }
-
-public synchronized void removeService(MyService service) { this.services.remove(service); }
-```
-
-### Component with configuration
-
-```java
-@Component(service = MyConfiguredService.class,
-           configurationPid = "org.example.myservice",
-           configurationPolicy = ConfigurationPolicy.OPTIONAL)
-public class MyConfiguredService {
-
-    @Activate
-    public void activate(Map<String, Object> props) {
-        String value = (String) props.getOrDefault("myProperty", "default");
-    }
-
-    @Modified
-    public void modified(Map<String, Object> props) { }
-}
-```
-
-Configuration file: `src/main/resources/META-INF/configurations/org.example.myservice.cfg`
-
----
-
-## 4. Blueprint XML (deprecated in 8.2)
-
-Do not use for new development. For legacy modules only. Files go in `OSGI-INF/blueprint/`.
-
----
-
-## 5. Package imports and exports
-
-### Manually adding imports
-
-```xml
-<jahia.modules.importPackage>org.jahia.defaults.config.spring,org.example.api</jahia.modules.importPackage>
-```
-
-Or in bundle plugin instructions:
-```xml
-<Import-Package>
-  org.example.api,
-  com.optional.pkg;resolution:=optional,
-  *
-</Import-Package>
-```
-
-### Exporting packages
-
-```xml
-<export-package>org.example.mymodule.api</export-package>
-```
-
----
-
-## 6. Embedding vs importing libraries
-
-### Option 1: Embed as JAR inside module JAR (easiest)
-
-```xml
-<Embed-Dependency>*;scope=compile|runtime;type=!pom;inline=false</Embed-Dependency>
-```
-
-To exclude a dependency from embedding, use `<scope>provided</scope>`.
-
-**Caution:** `Embed-Transitive>true</Embed-Transitive>` embeds ALL transitive dependencies — use carefully.
-
----
-
-## 7. Service export between modules
-
-### Provider module
-
-```java
-@Component(service = {DataService.class})
-public class DataServiceImpl implements DataService {
-    @Override
-    public List<String> getData() { return Arrays.asList("item1", "item2"); }
-}
-```
-
-pom.xml: `<export-package>org.example.moduleA.api</export-package>`
-
-### Consumer module
-
-```java
-@Component(service = MyConsumer.class)
-public class MyConsumer {
-    @Reference
-    public void setDataService(DataService dataService) { this.dataService = dataService; }
-}
-```
-
-pom.xml:
-```xml
-<jahia-depends>moduleA-artifactId</jahia-depends>
-<jahia.modules.importPackage>org.example.moduleA.api</jahia.modules.importPackage>
-```
-
----
-
-## 8. Available Jahia OSGi services
-
-Key Jahia services accessible via `@Reference`:
-
-| Interface | Description |
-|-----------|-------------|
-| `JahiaTemplateManagerService` | Template package registry, module lifecycle |
-| `JahiaUserManagerService` | User CRUD and lookup |
-| `JahiaGroupManagerService` | Group management |
-| `JCRSessionFactory` | JCR session factory |
-| `JahiaSitesService` | Site management |
-| `RenderService` | Content rendering |
-| `CacheService` | Cache management |
-| `WorkflowService` | Workflow management |
-
----
-
-## 9. Bundle lifecycle states
-
-| State | Description |
-|-------|-------------|
-| `INSTALLED` | Bundle JAR is installed but requirements not resolved yet |
-| `RESOLVED` | All package dependencies resolved but not started |
-| `STARTING` | Bundle activator is running |
-| `ACTIVE` | Bundle is fully started and operational |
-| `STOPPING` | Bundle is being stopped |
-| `UNINSTALLED` | Bundle has been removed |
-
-A bundle stuck in `RESOLVED` but not `ACTIVE` usually means an `@Activate` method threw an exception or a required `@Reference` could not be resolved.

package/dist/codex/.agents/skills/jahia-dev-java/references/rendering.md

@@ -1,191 +0,0 @@
-# Jahia Rendering Reference
-
-## Table of Contents
-1. [View script selection](#1-view-script-selection)
-2. [JSP rendering with taglibs](#2-jsp-rendering-with-taglibs)
-3. [Templates, areas, and cascading](#3-templates-areas-and-cascading)
-4. [Caching directives](#4-caching-directives)
-5. [Navigation menus](#5-navigation-menus)
-6. [Rendering filters](#6-rendering-filters)
-7. [List rendering](#7-list-rendering)
-
----
-
-## 1. View script selection
-
-**JSP naming convention:**
-```
-src/main/webapp/{nodeType_with_slash}/{templateType}/{viewName}.{displayType}.jsp
-```
-
-Examples:
-```
-src/main/webapp/jnt_article/html/article.jsp          # default view
-src/main/webapp/jnt_article/html/article.summary.jsp  # "summary" named view
-src/main/webapp/jnt_article/json/article.json.jsp     # JSON template type
-src/main/webapp/jnt_article/html/article.hidden.header.jsp  # hidden view
-```
-
-**Prefix `hidden.`** on a view name to exclude it from the UI view selector.
-
----
-
-## 2. JSP rendering with taglibs
-
-### Standard taglib declarations
-```jsp
-<%@ taglib prefix="template" uri="http://www.jahia.org/tags/templateLib" %>
-<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
-<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>
-<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
-<%@ taglib prefix="jcr" uri="http://www.jahia.org/tags/jcr" %>
-<%@ taglib prefix="ui" uri="http://www.jahia.org/tags/uiComponentsLib" %>
-```
-
-### Key implicit variables
-
-| Variable | Type | Description |
-|----------|------|-------------|
-| `currentNode` | `JCRNodeWrapper` | The node being rendered |
-| `currentUser` | `JahiaUser` | The currently logged-in user |
-| `renderContext` | `RenderContext` | Current rendering context |
-| `url` | `URLGenerator` | URL generation helper |
-
-### Common template taglib usage
-```jsp
-<template:module node="${currentNode}" view="summary"/>
-<template:area path="maincontent"/>
-<template:addCacheDependency node="${commentNode}"/>
-<template:link node="${targetNode}"/>
-```
-
-### Full JSP view example
-```jsp
-<%@ taglib prefix="template" uri="http://www.jahia.org/tags/templateLib" %>
-<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
-<%@ taglib prefix="fn" uri="http://java.sun.com/jsp/jstl/functions" %>
-
-<c:set var="title" value="${currentNode.properties['jcr:title'].string}"/>
-<c:set var="body" value="${currentNode.properties['body'].string}"/>
-
-<article class="my-article">
-    <h1>${fn:escapeXml(title)}</h1>
-    <div class="body">${body}</div>
-    <template:area path="related-content"/>
-</article>
-```
-
----
-
-## 3. Templates, areas, and cascading
-
-Page rendering cascades: page → home template → base template → template view.
-
-**Absolute areas** (`level` attribute): use an ancestor path instead of the template sequence.
-- Level 0 = home page
-- Level 1 = first sub-page level
-
----
-
-## 4. Caching directives
-
-### Per-view cache configuration
-
-Create a `.properties` file alongside the JSP:
-
-```properties
-# jnt_banner/html/banner.properties
-cache.expiration=30      # Cache for 30 seconds
-# cache.expiration=-1   # Never cache this view
-cache.perUser=true       # Cache per user
-cache.mainResource=true  # Cache depends on the main resource
-```
-
-### Adding cache dependencies in JSPs
-
-```jsp
-<template:addCacheDependency node="${commentsNode}"/>
-<template:addCacheDependency
-    flushOnPathMatchingRegexp="\Q${renderContext.mainResource.node.path}\E/.*/comments/.*"/>
-```
-
----
-
-## 5. Navigation menus
-
-```jsp
-<jcr:node var="siteNode" path="${renderContext.site.path}"/>
-<c:set var="homeNode" value="${siteNode.node['home']}"/>
-
-<nav>
-  <ul>
-    <c:forEach var="pageNode" items="${homeNode.nodes}">
-      <c:if test="${pageNode.nodeType.name == 'jnt:page'}">
-        <li>
-          <template:link node="${pageNode}">
-            <c:out value="${pageNode.properties['jcr:title'].string}"/>
-          </template:link>
-        </li>
-      </c:if>
-    </c:forEach>
-  </ul>
-</nav>
-```
-
----
-
-## 6. Rendering filters
-
-Filters intercept every module render. Extend `AbstractFilter` and register as OSGi `RenderFilter` services.
-
-### Priority rules
-- Priority > 16: runs once, result is cached
-- Priority < 16: runs on EVERY request (very expensive — avoid)
-
-### Filter implementation
-```java
-@Component(service = RenderFilter.class)
-public class MyFilter extends AbstractFilter {
-
-    @Activate
-    public void activate() {
-        setPriority(20);
-        setApplyOnConfigurations("page");
-        setApplyOnTemplateTypes("html,html-*");
-        setApplyOnNodeTypes("jnt:myContent");
-    }
-
-    @Override
-    public String execute(String previousOut, RenderContext renderContext,
-            Resource resource, RenderChain chain) throws Exception {
-        String output = super.execute(previousOut, renderContext, resource, chain);
-        return output;
-    }
-}
-```
-
----
-
-## 7. List rendering
-
-The `jmix:list` mixin provides built-in list rendering.
-
-### moduleMap parameters
-
-| Parameter | Description |
-|-----------|-------------|
-| `currentList` | Iterable of nodes to display |
-| `begin` | Start index |
-| `end` | End index |
-| `listQuery` | JCR SQL2 query |
-| `subNodesView` | View name used for child nodes |
-| `editable` | Whether list is editable (default: true) |
-
-### Query-based list example (`hidden.load.jsp`)
-```jsp
-<query:definition var="listQuery"
-    statement="SELECT * FROM [jnt:article] WHERE ISDESCENDANTNODE('${renderContext.mainResource.node.path}') ORDER BY [jcr:lastModified] DESC"
-    limit="10"/>
-<c:set target="${moduleMap}" property="listQuery" value="${listQuery}"/>
-<c:set target="${moduleMap}" property="editable" value="false"/>
-```