@jahia/agentic 0.0.0

package/dist/opencode/.agents/skills/jahia-dev-ops/references/provisioning.md

@@ -0,0 +1,269 @@
+# Jahia Provisioning Reference
+
+## Provisioning API overview
+
+The Jahia Provisioning API (introduced in DX 8.x) executes YAML scripts that
+install modules, create sites, configure OSGi services, and seed JCR content.
+Scripts can be:
+
+- Placed in `/var/jahia/patches/` — executed automatically at startup.
+- POSTed to the REST endpoint: `POST /modules/api/provisioning`.
+
+## REST endpoint
+
+```
+POST /modules/api/provisioning
+Authorization: Basic <base64(root:password)>
+Content-Type: application/yaml   (or multipart/form-data)
+
+<provisioning script body>
+```
+
+### Upload via curl
+
+```bash
+curl -u root:changeme \
+     -X POST \
+     -H "Content-Type: application/yaml" \
+     --data-binary @my-script.yaml \
+     http://localhost:8080/modules/api/provisioning
+```
+
+### Upload via multipart (with file)
+
+```bash
+curl -u root:changeme \
+     -F "script=@my-script.yaml" \
+     http://localhost:8080/modules/api/provisioning
+```
+
+## Script structure
+
+```yaml
+# provisioning-script.yaml
+- installOrUpgradeModules:
+    - url: "mvn:org.jahia.modules/article/3.5.0"
+    - url: "file:///var/jahia/modules/my-custom-module-1.0.jar"
+
+- createSite: ""
+  siteKey: mySite
+  title: "My Site"
+  defaultLanguage: en
+  serverName: localhost
+  templateSet: my-template-set
+
+- importSite:
+    siteKey: mySite
+    uri: "file:///var/jahia/imports/mySite-export.zip"
+```
+
+## Common provisioning operations
+
+### Install / upgrade a module from Maven
+
+```yaml
+- installOrUpgradeModules:
+    - url: "mvn:org.jahia.modules/bootstrap4-core/4.0.0"
+    - url: "mvn:org.jahia.modules/bootstrap4-components/4.0.0"
+```
+
+### Install from a local file
+
+```yaml
+- installOrUpgradeModules:
+    - url: "file:///var/jahia/modules/my-module-1.0.jar"
+```
+
+### Enable / start a module
+
+```yaml
+- startModules:
+    - name: my-module
+```
+
+### Disable / stop a module
+
+```yaml
+- stopModules:
+    - name: my-module
+```
+
+### Uninstall a module
+
+```yaml
+- uninstallModules:
+    - name: my-module
+```
+
+### Create a virtual site
+
+> ⚠️ **CRITICAL — Jahia 8.2 syntax**: use `- createSite: ""` with properties at the **same indentation level**. There are **two common mistakes that both silently return HTTP 200 but create nothing**:
+> - ❌ `- createSite:` with nested properties (missing `""`)
+> - ❌ `- createVirtualSite:` (old name, no longer valid)
+> 
+> **Always use a file-based approach** to avoid shell quoting issues:
+
+```bash
+cat > /tmp/create-site.yaml <<'EOF'
+- createSite: ""
+  siteKey: acme
+  title: "ACME Corp"
+  defaultLanguage: en
+  serverName: localhost
+  templateSet: acme-template-set
+EOF
+
+curl -u root:root1234 -X POST -H "Content-Type: application/yaml" \
+  --data-binary @/tmp/create-site.yaml \
+  http://localhost:8080/modules/api/provisioning
+```
+
+The API returns `HTTP 200` with an empty body. **Always verify** the site was created — HTTP 200 is not sufficient confirmation:
+
+```bash
+curl -s -u root:root1234 \
+  -H "Content-Type: application/json" -H "Origin: http://localhost:8080" \
+  -X POST http://localhost:8080/modules/graphql \
+  -d '{"query":"{ jcr { nodeByPath(path: \"/sites/acme\") { name } } }"}'
+```
+
+If the response contains `"name": "acme"`, the site exists. If it returns `null`, the site was not created — recheck the YAML format.
+
+### Delete a virtual site
+
+```bash
+curl -u root:root1234 \
+     -X POST \
+     -H "Content-Type: application/yaml" \
+     --data-binary '- deleteSite: ""
+  siteKey: acme' \
+     http://localhost:8080/modules/api/provisioning
+```
+
+### Import a site export ZIP
+
+```yaml
+- importSite:
+    siteKey: acme
+    uri: "file:///var/jahia/imports/acme-export.zip"
+    rootUsersGroup: site-admins
+```
+
+### Execute a Groovy script
+
+```yaml
+- executeScript:
+    script: "file:///var/jahia/patches/migrate-content.groovy"
+```
+
+Or inline:
+
+```yaml
+- executeScript:
+    scriptContent: |
+      import org.jahia.services.content.*
+      def session = JCRSessionFactory.getInstance().getCurrentSystemSession("default", null, null)
+      // ... do work ...
+      session.save()
+```
+
+### Set a system property / OSGi configuration
+
+```yaml
+- setSystemProperty:
+    name: my.custom.property
+    value: "my-value"
+```
+
+```yaml
+- setOsgiConfiguration:
+    pid: "org.jahia.services.content.nodetypes.NodeTypeRegistry"
+    properties:
+      autoDeployBundles: "true"
+```
+
+### Add a user
+
+```yaml
+- addUser:
+    username: john.doe
+    password: secret123
+    email: john.doe@example.com
+    firstName: John
+    lastName: Doe
+    roles:
+      - site-administrator:acme
+```
+
+### Grant a role on a node
+
+```yaml
+- grantRoles:
+    path: /sites/acme
+    principal: "u:john.doe"
+    roles:
+      - site-administrator
+```
+
+## Patches directory
+
+Files placed in `/var/jahia/patches/` are executed **once** at startup
+(Jahia records which files have already been applied):
+
+```
+/var/jahia/patches/
+  cfg/               ← OSGi .cfg files
+  spring/            ← Spring XML context overrides
+  groovy/            ← Groovy scripts (executed once)
+  yaml/              ← Provisioning YAML scripts (executed once)
+```
+
+Mount a host directory here to inject patches without rebuilding the image:
+
+```yaml
+volumes:
+  - ./patches:/var/jahia/patches
+```
+
+## Execution order and idempotency
+
+- Provisioning YAML scripts in `patches/yaml/` are sorted alphabetically.
+  Prefix filenames with a two-digit index (`01-modules.yaml`, `02-sites.yaml`)
+  to control order.
+- Most operations are idempotent: `installOrUpgradeModules` skips if the exact
+  version is already installed; `createVirtualSite` skips if the site key exists.
+- Groovy scripts in `patches/groovy/` run exactly once; rename the file to
+  force re-execution.
+
+## Checking provisioning status
+
+```bash
+# View provisioning log output (appears in jahia.log)
+docker compose exec jahia grep -i "provisioning\|install.*module\|createVirtualSite" /var/log/jahia/jahia.log
+
+# List applied patches via Karaf
+ssh -p 7770 karaf@localhost
+# In Karaf:
+jahia:patches-list
+```
+
+## jCustomer (Unomi) provisioning
+
+Unomi uses its own REST API and YAML/JSON rules. Key endpoints:
+
+```bash
+# Import a scope
+curl -u karaf:karaf -X POST \
+     -H "Content-Type: application/json" \
+     -d '{"itemId":"mySite","itemType":"scope"}' \
+     http://localhost:8181/cxs/scopes
+
+# Import a rule
+curl -u karaf:karaf -X POST \
+     -H "Content-Type: application/json" \
+     -d @my-rule.json \
+     http://localhost:8181/cxs/rules
+
+# Reload rules from classpath
+curl -u karaf:karaf -X POST http://localhost:8181/cxs/rules/resetQueries
+```

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

@@ -0,0 +1,297 @@
+---
+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