@jahia/agentic 0.1.1 → 0.3.0

package/dist/cursor/.agents/skills/jahia-java-concurrency/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: jahia-java-concurrency
+description: Thread safety patterns for Jahia Java backend development in a multi-threaded web application. Covers volatile, locking, atomic variables, thread-safe collections, immutability, and common pitfalls that cause data races, stale reads, and silent corruption. Load when implementing or reviewing any class that holds mutable state accessible from multiple threads — OSGi services, caches, static fields, background workers, event listeners.
+allowed-tools: Read
+---
+
+# Concurrency and Thread Safety for Jahia Java Backend
+
+In a Jahia webapp, every OSGi service is a singleton — its instance fields are shared across every concurrent request, publication job, event listener, and background thread. A field that looks fine in a single-threaded test can silently corrupt data or read stale values under real load.
+
+This skill covers the correct patterns and the pitfalls. Both developers and reviewers use it.
+
+> OSGi-specific concurrency (`@Modified` config reload, `@Reference` dynamic rebinding) is covered in `/jahia-java-osgi`. This skill covers the general Java concurrency model applicable to all backend code.
+
+---
+
+## The three questions to ask about any mutable field
+
+Before writing or reviewing any instance or static field in a service:
+
+1. **Can it be written by more than one thread?** If yes → needs synchronization or an atomic type.
+2. **Can it be read while another thread is writing it?** If yes → at minimum needs `volatile`.
+3. **Are read + write part of a compound action** (check-then-act, read-modify-write)? If yes → `volatile` alone is not enough, needs a lock or an atomic with CAS.
+
+---
+
+## Immutability — the first line of defence
+
+### Correct approach
+
+Prefer immutable objects. An immutable object needs no synchronization — it is inherently thread-safe.
+
+- Make fields `final` wherever possible.
+- Use `record` types for config/value objects (all fields are final by definition).
+- Use `List.of()`, `Map.of()`, `Set.of()` for collections that do not change after construction.
+- Return copies or unmodifiable views of mutable internal collections rather than the live reference.
+
+### Pitfall
+
+```java
+// dangerous — caller can mutate the internal list
+public List<String> getAllowedRoles() {
+    return allowedRoles; // returns live mutable reference
+}
+```
+
+Return `Collections.unmodifiableList(allowedRoles)` or `List.copyOf(allowedRoles)` instead.
+
+---
+
+## `volatile` — correct use and limits
+
+### Correct use
+
+`volatile` guarantees **visibility**: a write to a `volatile` field is immediately visible to all subsequent reads in other threads. Use it when:
+
+- One thread writes, many threads read (no compound action needed).
+- The written value is a single reference or primitive (not two fields that must be updated atomically together).
+
+```java
+// correct — single writer (SCR @Modified), many readers
+private volatile Config config;
+
+@Activate @Modified
+void activate(Cfg cfg) {
+    this.config = new Config(cfg); // atomic reference swap
+}
+```
+
+### Limits — volatile is NOT enough for compound actions
+
+```java
+// WRONG — read-modify-write is not atomic even with volatile
+private volatile int counter = 0;
+public void increment() {
+    counter++; // read, increment, write — three steps, not one
+}
+```
+
+Two threads can both read `counter = 5`, both compute `6`, and both write `6` — losing one increment. Use `AtomicInteger.incrementAndGet()` instead.
+
+Similarly, volatile does not protect **two fields that must be consistent with each other**:
+
+```java
+// WRONG — reader can see updated 'host' with old 'port'
+private volatile String host;
+private volatile int port;
+```
+
+Bundle related fields into a single immutable record and swap the reference atomically (as shown in `/jahia-java-osgi`).
+
+---
+
+## Atomic variables
+
+Use `java.util.concurrent.atomic` for lock-free, thread-safe single-value updates:
+
+| Need | Type |
+|---|---|
+| Thread-safe counter | `AtomicInteger` / `AtomicLong` |
+| Thread-safe reference swap | `AtomicReference<T>` |
+| Conditional update (compare-and-swap) | `AtomicReference.compareAndSet()` |
+| Accumulator under high contention | `LongAdder` (more scalable than `AtomicLong` for pure counting) |
+
+### Check-then-act with `compareAndSet`
+
+```java
+// correct — atomic conditional update
+AtomicReference<State> stateRef = new AtomicReference<>(State.IDLE);
+
+public boolean tryStart() {
+    return stateRef.compareAndSet(State.IDLE, State.RUNNING);
+}
+```
+
+Two threads calling `tryStart()` concurrently: only one gets `true`. No lock needed.
+
+---
+
+## Synchronized blocks and `ReentrantLock`
+
+### When to use
+
+Use explicit locking when:
+- The critical section spans multiple statements that must execute atomically.
+- You need read/write distinction (`ReadWriteLock`).
+- You need a timed or interruptible lock attempt (`ReentrantLock.tryLock(timeout)`).
+
+### Correct approach
+
+```java
+// small, focused critical section
+private final Object lock = new Object();
+private List<String> items = new ArrayList<>();
+
+public void addItem(String item) {
+    synchronized (lock) {
+        items.add(item);
+    }
+}
+
+public List<String> snapshot() {
+    synchronized (lock) {
+        return List.copyOf(items); // return a copy, not the live list
+    }
+}
+```
+
+### Pitfalls
+
+- **Locking on `this`.** Callers can also `synchronized(service)` from outside, causing unexpected contention or deadlock. Prefer a private `final Object lock`.
+- **Holding a lock during I/O or JCR calls.** A lock held while doing a JCR query or an HTTP call blocks all other threads waiting for it. Move I/O outside the critical section; only protect the state mutation.
+- **Inconsistent lock object.** Two methods protecting the same state must use the same lock.
+- **Deadlock.** Two threads each holding lock A and waiting for lock B. Always acquire multiple locks in the same fixed order. Prefer `tryLock(timeout)` and fail gracefully rather than block indefinitely.
+
+### `ReadWriteLock` for read-heavy state
+
+```java
+private final ReadWriteLock rwLock = new ReentrantReadWriteLock();
+private Map<String, String> cache = new HashMap<>();
+
+public String get(String key) {
+    rwLock.readLock().lock();
+    try { return cache.get(key); }
+    finally { rwLock.readLock().unlock(); }
+}
+
+public void put(String key, String value) {
+    rwLock.writeLock().lock();
+    try { cache.put(key, value); }
+    finally { rwLock.writeLock().unlock(); }
+}
+```
+
+Multiple readers proceed concurrently; a writer gets exclusive access. Worth the complexity only when reads heavily outnumber writes.
+
+---
+
+## Thread-safe collections
+
+| Use case | Correct type | What NOT to use |
+|---|---|---|
+| Concurrent map (read-heavy or write-heavy) | `ConcurrentHashMap` | `HashMap` (not thread-safe), `Collections.synchronizedMap` (full lock on every op) |
+| Concurrent list, infrequent writes | `CopyOnWriteArrayList` | `ArrayList`, `Collections.synchronizedList` |
+| Concurrent queue / work queue | `LinkedBlockingQueue`, `ArrayBlockingQueue` | `LinkedList` |
+| Set | `ConcurrentHashMap.newKeySet()` | `HashSet` |
+| Cache with eviction | `Caffeine` or `Guava Cache` | `HashMap` with manual cleanup |
+
+### Pitfall — compound actions on `ConcurrentHashMap`
+
+```java
+// WRONG — check-then-put is not atomic
+if (!map.containsKey(key)) {
+    map.put(key, value);
+}
+// CORRECT
+map.putIfAbsent(key, value);
+// or for a more complex compute:
+map.computeIfAbsent(key, k -> expensiveCreate(k));
+```
+
+Even `ConcurrentHashMap` does not make compound actions atomic unless you use the atomic methods (`putIfAbsent`, `computeIfAbsent`, `merge`, `compute`).
+
+---
+
+## Static fields
+
+### Pitfall
+
+Static fields are shared across all class loader instances — effectively global state in a webapp. A static mutable field is the most dangerous form of shared state: it is not scoped to a component lifecycle, so it outlives bundle reactivations and can carry stale state.
+
+```java
+// dangerous — static mutable state in a webapp
+private static Map<String, Object> cache = new HashMap<>();
+```
+
+**Rule:** static fields in a Jahia module must be either:
+- `final` and truly immutable (constants, loggers), or
+- `volatile` / concurrent-typed with documented thread-safety, or
+- `ThreadLocal` (thread-scoped, not shared).
+
+If you need a cache or shared service state, use an OSGi `@Component` instance field — the OSGi lifecycle manages it correctly.
+
+---
+
+## `ThreadLocal`
+
+`ThreadLocal` gives each thread its own isolated copy of a variable. Correct for per-request state (locale, user context, transaction context).
+
+### Pitfall — thread pool reuse
+
+Jahia uses thread pools. A `ThreadLocal` set during request A and not cleared will be visible during a later request B handled by the same thread:
+
+```java
+// always clean up in a finally block
+threadLocal.set(value);
+try {
+    doWork();
+} finally {
+    threadLocal.remove(); // mandatory
+}
+```
+
+Failing to call `remove()` is a P1 finding — stale user context or locale leaked to subsequent requests.
+
+---
+
+## JCR sessions are NOT thread-safe
+
+A `JCRSessionWrapper` must never be shared across threads. Do not store a session as an instance field of an OSGi service and reuse it across requests.
+
+```java
+// WRONG — shared session across threads
+@Component
+public class MyService {
+    private JCRSessionWrapper session; // one session, all threads — crash under concurrency
+}
+```
+
+Always obtain a fresh session per-thread (and per-locale where i18n matters) and close it in a `finally` block or via `JCRTemplate`.
+
+---
+
+## Lazy initialization
+
+### Correct approach — `volatile` + double-checked locking
+
+```java
+private volatile ExpensiveObject instance;
+
+public ExpensiveObject get() {
+    if (instance == null) {                    // first check (no lock)
+        synchronized (this) {
+            if (instance == null) {            // second check (with lock)
+                instance = new ExpensiveObject();
+            }
+        }
+    }
+    return instance;
+}
+```
+
+Without `volatile`, the JVM may publish a partially-constructed object due to instruction reordering. **`volatile` on the field is mandatory for double-checked locking to be correct.**
+
+### Simpler alternative — holder idiom
+
+```java
+// no synchronization needed — class loading is inherently thread-safe
+private static class Holder {
+    static final ExpensiveObject INSTANCE = new ExpensiveObject();
+}
+public static ExpensiveObject get() { return Holder.INSTANCE; }
+```
+
+---
+
+## Review checklist
+
+When reviewing any class in a Jahia module, check:
+
+1. **Instance fields of `@Component` services** — are mutable ones `volatile`, atomic, or synchronized?
+2. **Static mutable fields** — flag immediately; require justification and correct synchronization.
+3. **Compound actions** — every check-then-act or read-modify-write on a shared field needs a lock or atomic CAS.
+4. **Collections returned from getters** — are they copies or unmodifiable views?
+5. **JCR sessions** — never stored as instance fields; always obtained and closed per-thread.
+6. **`ThreadLocal`** — always cleaned up in a `finally` block.
+7. **Locks** — held for the minimum possible time; no I/O inside a critical section.
+8. **Undocumented thread-safety contract** — if the class is not internally thread-safe, its Javadoc must say so and name the required external synchronization.

package/dist/cursor/.agents/skills/jahia-java-jcr/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: jahia-java-jcr
+description: JCR patterns for Jahia Java development — correct usage of sessions, workspaces, node operations, mixins, locks, and versioning. Covers both the right approach and the pitfalls that cause data loss, security gaps, or concurrency bugs. Load when implementing or reviewing any class that reads or writes the JCR.
+allowed-tools: Read
+---
+
+# JCR Patterns for Jahia Java
+
+This skill covers how to use the JCR correctly in a Jahia Java module. Each section states the correct approach first, then the pitfall to avoid. Both developers and reviewers use this skill: developers to implement correctly from the start, reviewers to identify violations.
+
+---
+
+## Session lifecycle and workspace
+
+### Correct approach
+
+- **User session** (`JCRSessionWrapper` obtained from `JCRSessionFactory.getCurrentUserSession(workspace, locale)`) enforces ACLs. Use this for any operation that should respect the user's permissions.
+- **System session** (`JCRTemplate.doExecuteWithSystemSession` or `JCRSessionFactory.getCurrentSystemSession`) bypasses ACLs. Use only when a permission check was performed earlier in the call chain and documented explicitly.
+- **Workspace boundary.** `default` (edit workspace, where authors work) vs `live` (published, visitor-facing). Public-facing reads must use `live`. Admin UIs use `default`. Writes that must appear publicly go through `PublicationService` — never write to `live` directly unless you have a specific operational reason.
+- **Locale.** `getCurrentUserSession(workspace, locale)` resolves i18n properties. Omitting the locale falls back to default — correct only if the caller truly does not need a specific locale.
+
+### Pitfalls
+
+- **System session without prior permission check.** When a system session performs an operation, trace back to where the target node ID came from. If it came from a user-session lookup with no further authorization check, the user-session lookup is the entire security boundary. Document this explicitly. If it is absent, it is a security finding.
+- **Workspace mismatch.** Reading from `default` when rendering public pages, or writing to `live` when the intended target is `default`. Both produce silent wrong behavior.
+- **Locale omission.** Calling without locale and reading `jcr:title` or any i18n property — the result is locale-nondeterministic.
+
+---
+
+## Node names — JSR-283 conformance
+
+### Correct approach
+
+Forbidden characters in a local name: `/ : [ ] | *`, plus whitespace-only names. Use `JCRContentUtils.escapeLocalNodeName` to sanitize any externally-supplied string before using it as a node name.
+
+### Pitfall
+
+Hand-rolled filename sanitization (regex replacements, `String.replace`) is almost always incomplete. The JSR-283 character set is non-obvious. Use the platform helper.
+
+---
+
+## Same-name siblings (SNS)
+
+### Correct approach
+
+Two children with the same name under the same parent are indexed `node[1]`, `node[2]`. If you need to find-or-create by name under concurrent load, either:
+- Lock the parent node before the check-then-create sequence.
+- Use a unique-by-construction name (UUID, slug+timestamp) and store the display name as a property.
+
+### Pitfall
+
+Unguarded find-or-create patterns under any concurrent caller (publication pipeline, event listener, HTTP endpoint) hit `ItemExistsException` or silently create a duplicate SNS node. Under guest endpoints this is a P1 finding.
+
+---
+
+## Mixin handling
+
+### Correct approach
+
+- Before setting properties specific to a mixin, call `node.addMixin("ns:myMixin")` if the node does not already have it.
+- Use `node.isNodeType("ns:myMixin")` to classify behavior rather than switching on concrete node type strings from another module. This keeps the engine decoupled from specific UI modules.
+- **Definition-level vs instance-level mixins.** Mixins applied in the CND definition are always present on every node of that type. Mixins added at runtime via `addMixin()` are instance-level — they must be captured and restored explicitly in any serialization/versioning path.
+
+### Pitfalls
+
+- Assuming a mixin is present because the content type "should" have it — this breaks when the content was created before the mixin was added to the definition.
+- Hardcoded concrete node-type strings from another module (`fmdb:inputText`, `fmdb:textarea`). The correct pattern is classifying mixins in the engine's own CND.
+- Serialization paths (export, versioning, diff) that capture `properties` but ignore `mixinNodeTypesNames` — instance-level mixin changes are silently lost on restore.
+
+---
+
+## Versioning and checkout
+
+### Correct approach
+
+Writing to a `mix:versionable` node requires a `checkout()` call first. After saving, call `checkin()` if the workflow requires it. Jahia's publication service handles this for standard publication flows — only write direct checkout/checkin in custom write paths.
+
+### Pitfall
+
+Writing to a versioned node without `checkout()` throws `VersionException`. Code that assumes the node is always in a checked-out state breaks whenever the publication service last left it checked in.
+
+---
+
+## Locking
+
+### Correct approach
+
+Respect existing locks before performing write operations. Before clearing a lock:
+1. Check whether the lock is owned by the current operation or by an external caller (another user, a publication job, a workflow).
+2. If the lock is external, **fail the operation** with a clear error — do not clear it silently and continue.
+3. Document the thread-safety contract of any write path that involves locking.
+
+### Pitfall
+
+```java
+// dangerous — clears locks unconditionally, continues even if clearing fails
+JCRContentUtils.clearAllLocks(node);
+restoreContent(node, version);
+```
+
+A node locked by an active publication job, a concurrent editor, or a workflow step is locked for a reason. Clearing it unconditionally can corrupt in-progress work. This is a P0 finding if the code ships to production; P1 if guarded by a feature flag that is off by default.
+
+---
+
+## JCR event listeners
+
+### Correct approach
+
+Register listeners in `@Activate` and unregister in `@Deactivate`. Use `JCRObservationManager` or Jahia's `DefaultEventListener` base class. Keep listeners short — heavy work should be dispatched to a separate thread or scheduled task.
+
+Event listener disabling via `JCRObservationManager.setAllEventListenersDisabled(true)` is **thread-local** in Jahia, not global. It is safe to use inside a request thread or a background thread without affecting other concurrent threads.
+
+### Pitfalls
+
+- Listeners registered but never unregistered — accumulate across reactivations, causing duplicate event processing.
+- Blocking I/O or JCR writes inside a synchronous event listener — holds the observation thread and causes lag across the entire event queue.
+
+---
+
+## `RepositoryException` handling
+
+### Correct approach
+
+- On a **security gate** (checking node type, checking permission): if the check throws, fail closed. Do not let the operation continue.
+- On a **data read**: if partial results would be misleading downstream, fail or return an empty result with a logged warning.
+
+### Pitfall
+
+```java
+try {
+    requiresAuth = node.isNodeType("...");
+} catch (RepositoryException e) {
+    log.warn(...);
+    return; // operation continues — fails open
+}
+```
+
+Fail-open on a security gate is a P0 finding. Fail-open on a data read producing misleading partial state is P0 or P1 depending on downstream impact.
+
+---
+
+## JCR SQL2 queries
+
+### Correct approach
+
+- Scope queries with `ISDESCENDANTNODE(alias, '/sites/...')` — never query the entire repository.
+- Use specific node types, not `nt:base`. Use `jmix:searchable` for broad content queries.
+- Parameterize with bind variables, not string concatenation.
+- Set a `LIMIT` on unbounded queries.
+
+### Pitfall
+
+`SELECT * FROM [nt:base]` against the full repository is a full-scan and blocks the query index. String-concatenated queries are a JCR injection vector (less critical than SQL injection but still wrong).

package/dist/cursor/.agents/skills/jahia-java-osgi/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: jahia-java-osgi
+description: OSGi component patterns for Jahia Java development — correct usage of @Component lifecycle, @Reference, Export-Package, whiteboard services, and thread safety. Covers both the right approach and the pitfalls that cause NPEs, stale state, or leaked internals. Load when implementing or reviewing any class annotated with @Component, @Reference, or @Activate.
+allowed-tools: Read
+---
+
+# OSGi Component Patterns for Jahia Java
+
+This skill covers how to write OSGi components correctly in a Jahia Java module. Each section states the correct approach first, then the pitfall to avoid. Both developers and reviewers use this skill.
+
+For broader Java concurrency patterns (atomic variables, locking, thread-safe collections, `ThreadLocal`, JCR session threading) that apply beyond OSGi components, load `/jahia-java-concurrency`.
+
+For a comprehensive OSGi reference (bundle lifecycle, Blueprint XML, Karaf tooling, service registry), load the `jahia-dev-java` skill and read `references/osgi.md`.
+
+---
+
+## Component state and configuration reload
+
+### Correct approach
+
+`@Component` services are singletons. Configuration is delivered via `@Activate` (on first start) and `@Modified` (on config change). `@Modified` runs on a different thread than service consumers.
+
+The safe pattern for config reload:
+
+```java
+private volatile Config config;
+
+record Config(String host, int port) {}
+
+@Activate @Modified
+public void activate(MyOsgiConfig cfg) {
+    this.config = new Config(cfg.host(), cfg.port());
+}
+
+public void doWork() {
+    var c = this.config; // snapshot once — atomic read
+    // use c.host(), c.port() ...
+}
+```
+
+A single `volatile` write (the reference swap) is atomically visible to all readers. Readers snapshot the reference once at method entry and work with the snapshot — they never see a half-updated config.
+
+### Pitfalls
+
+- **Mutable fields updated in `@Activate`/`@Modified` without `volatile` or synchronization.** A consumer thread can read a field while `@Modified` is updating it — data race. P1 finding.
+- **Multiple fields updated individually without synchronization.** Even with `volatile`, two separate field reads can see values from different config snapshots. Use a single `volatile Config` record, not individual `volatile String host; volatile int port`.
+
+---
+
+## Service references
+
+### Correct approach
+
+- `@Reference` fields are set by SCR before `@Activate`. Treat them as effectively final inside the component's methods.
+- For **mandatory** references (`cardinality = MANDATORY`), the component will not activate if the service is absent — null checks are not needed.
+- For **optional** references (`cardinality = OPTIONAL`), the field can be `null` — always guard.
+- For **dynamic** references (`policy = ReferencePolicy.DYNAMIC`), the field can be replaced at runtime. Snapshot it at method entry: `var svc = this.myService;` then use `svc`. Reading the field twice risks NPE if the service is unregistered between reads.
+
+### Pitfalls
+
+- **Non-mandatory `@Reference` accessed without null guard.** P1 — NPE in production when the referenced bundle is not deployed.
+- **Dynamic reference read twice without snapshot.** Between two reads the SCR may set the field to `null`. P1.
+- **`policyOption = GREEDY`.** SCR rebinds to a higher-ranked service when one appears. Code holding a reference to the old service instance keeps using a deactivated service. Document this if intentional.
+
+---
+
+## Lifecycle side effects
+
+### Correct approach
+
+Every side effect created in `@Activate` must be undone in `@Deactivate`. Components can be deactivated and re-activated on config changes (depending on `@Modified` policy). Failing to undo side effects causes them to accumulate across activations.
+
+Checklist:
+- Thread started in `@Activate` → stopped in `@Deactivate` (interrupt + join).
+- JCR event listener registered → unregistered.
+- Scheduled task registered → cancelled.
+- External connection opened → closed.
+- Cache populated → cleared or reseeded.
+
+### Pitfall
+
+A listener registered in `@Activate` but never unregistered in `@Deactivate` survives deactivation, fires events for a component that is no longer active, and duplicates on next activation. P1.
+
+---
+
+## Export-Package hygiene
+
+### Correct approach
+
+`Export-Package` in `pom.xml` defines what other bundles can import. It is the module's public API contract.
+
+- Export only interfaces and types in a dedicated `api` or `spi` sub-package.
+- Never export `*.impl`, `*.internal`, `*.actions` — the name signals private scope.
+- Never re-export third-party packages.
+- If the module advertises an SPI for external consumers, the SPI should live in a **separate Maven module** (`{name}-api`). Changing the runtime JAR then does not force a version bump on the API.
+
+### Pitfall
+
+Exporting implementation packages means any other bundle can import your internal classes. A refactor that renames or removes an internal class becomes a breaking change for dependent bundles. P1.
+
+---
+
+## Whiteboard pattern services
+
+Services registered as `@Component` — `Servlet`, `Filter`, `EventHandler`, GraphQL provider — are activated the moment the bundle starts. If the service is reachable over HTTP, it is as exposed as a `web.xml` servlet, with no extra protection by default. Apply the security mapping from `jahia-java-security` for every HTTP-reachable whiteboard service.
+
+---
+
+## Service locator anti-pattern
+
+### Correct approach
+
+Declare all dependencies as `@Reference` fields. SCR injects them before `@Activate`. The component's constructor or `@Activate` method has all dependencies available without any lookup.
+
+### Pitfall
+
+```java
+// anti-pattern — service locator inside a method
+MyService svc = (MyService) SpringContextSingleton.getBean("myService");
+```
+
+Service locator calls inside methods: hide the component's real dependencies, make the code impossible to unit-test, bypass SCR lifecycle guarantees, and can return stale or wrong beans after a context refresh. P2 in general code; P1 in a hot path or security-relevant method.
+
+---
+
+## Thread safety summary for reviewers
+
+When reviewing an `@Component` service, ask:
+
+1. Are there mutable instance fields? If yes — are they `volatile` or synchronized?
+2. Does the component react to `@Modified`? If yes — do consumers snapshot config at method entry?
+3. Are there `DYNAMIC` references? If yes — do callers snapshot the reference?
+4. Does the component start threads, register listeners, or open connections? If yes — does `@Deactivate` undo all of them?
+5. Does the component's Javadoc state its thread-safety contract? If the service is not internally safe, the caller must be told what external serialization is required.