@jahia/agentic 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # `@jahia/agentic`
 
+## 0.4.0
+
+* Specialized content modeling agent.
+
+## 0.3.0
+
+* Replaced GraphQL with MCP for content operations. (#6)
+
 ## 0.2.0
 
 * Added Java reviewer and Jahia-specific skills with concurrency pattern. (#4)

package/README.md

@@ -46,3 +46,31 @@ On harness changes, we task an agent to complete a long Jahia task end-to-end, a
 - SEO score
 
 There's room for improvement on these axes, but once perfected we will introduce a more complex prompt and assess the quality of the code and the edition experience produced.
+
+### Running a benchmark from a branch
+
+Trigger the benchmark workflow on any branch:
+
+```bash
+gh workflow run benchmark.yml --ref feat/my-branch
+```
+
+Monitor the run:
+
+```bash
+gh run list --workflow=benchmark.yml
+gh run watch          # live tail of the latest run
+```
+
+### Checking results
+
+Results are pushed to the `results` branch after each run. Fetch and inspect:
+
+```bash
+git fetch origin results
+git show origin/results:benchmark.json | jq '.[-1]'
+```
+
+This shows the latest result with pages, scores, duration, and token usage. Screenshots are stored alongside the JSON on the same branch.
+
+The aggregated dashboard for the `main` branch is published at [jahia.github.io/agentic](https://jahia.github.io/agentic/).

package/dist/claude/.claude/agents/cnd-child-nodes.md

@@ -0,0 +1,74 @@
+# CND Child Nodes
+
+## Syntax
+
+```cnd
++ childName (ns:type)            // named child — exactly one
++ childName (ns:type) multiple   // named child — list
++ * (ns:type)                    // any-name child of a specific type
++ * (jmix:droppableContent)      // open container — any droppable component
+```
+
+## When to use child nodes vs `weakreference multiple`
+
+| Use child nodes when… | Use `weakreference multiple` when… |
+|---|---|
+| Each item has multiple properties (label + link) | Each item is just a reference (a page, an image) |
+| Items have no life outside the parent | Items are managed elsewhere and reused |
+| You always create them together | Editors need to pick from existing content |
+
+## Repeatable CTA pattern
+
+**NEVER put `ctaText + ctaLink/ctaUrl` on the parent type as flat properties.**
+Model CTAs as child nodes — editors can then add multiple CTAs.
+
+```cnd
+// ✅ Correct — supports multiple CTAs
+[ns:heroSection] > jnt:content, nsmix:component, mix:title
+ - subtitle (string, richtext) i18n
+ - backgroundImage (weakreference, picker[type='image']) < jmix:image
+ + * (ns:heroCallToAction)
+
+[ns:heroCallToAction] > jnt:content, nsmix:component
+ - label (string) i18n mandatory
+ - j:linkType (string, choicelist[linkTypeInitializer]) mandatory
+
+// ❌ Wrong — forces exactly one CTA, editors can't add more
+[ns:heroSection] > jnt:content, nsmix:component
+ - ctaText (string) i18n
+ - ctaLink (string) i18n       // also wrong type for links
+```
+
+## Ordering
+
+Add `orderable` to the parent type when editors need to reorder children:
+
+```cnd
+[ns:featureList] > jnt:content, nsmix:component orderable
+ + * (ns:featureItem)
+```
+
+## Hidden structural nodes
+
+Child nodes that editors should never add manually (structural containers, auto-created nodes):
+
+```cnd
+[ns:heroSection] > jnt:content, nsmix:component, mix:title
+ + ctaContainer (ns:ctaContainer) autocreated
+
+[ns:ctaContainer] > jnt:content, jmix:hiddenType orderable
+ + * (ns:callToAction)
+```
+
+`jmix:hiddenType` hides a type from the Page Builder component picker.
+**Never use `jmix:studioOnly`** — it causes silent rendering issues.
+
+## Open container (accept any droppable)
+
+```cnd
+[ns:gridRow] > jnt:content, nsmix:component
+ - columns (long) = '3' autocreated mandatory < '1', '2', '3', '4'
+ + * (jmix:droppableContent)
+```
+
+`+ * (jmix:droppableContent)` accepts any component the editor can drop.

package/dist/claude/.claude/agents/cnd-jahia-mixins.md

@@ -0,0 +1,113 @@
+# Jahia Native Mixins & Types
+
+Source: https://github.com/Jahia/jahia/tree/master/war/src/main/webapp/WEB-INF/etc/repository/nodetypes
+Fetch this URL to verify before using any mixin not listed here.
+
+## Base types — always extend these
+
+| Type | Purpose |
+|---|---|
+| `jnt:content` | Base for all user content nodes — **always include** |
+| `jnt:page` | Page node — only for `jmix:mainResource` full-page types |
+| `jnt:file` | File node — for file references |
+
+## Mixins by use case
+
+### `mix:title` — preferred over a raw title property
+
+Adds `jcr:title` (string). Jahia's UI, breadcrumbs, SEO, and sitemap generation all read `jcr:title`.
+**Extend this instead of declaring `- title (string) i18n mandatory`.**
+
+```cnd
+[ns:article] > jnt:content, nsmix:component, mix:title
+```
+
+Access in view: `props["jcr:title"]`
+
+### `jmix:mainResource` — full-page content types only
+
+Makes a node accessible at its own URL. Use **only** for content that needs both a listing card AND a detail page (e.g. blog posts, team members, events). Do not add to navigation or visual composition types.
+
+```cnd
+[ns:blogPost] > jnt:content, mix:title, jmix:mainResource, nsmix:component
+```
+
+### `jmix:image` — image constraint for weakreference
+
+Use as the type constraint on image weakreference properties:
+
+```cnd
+- backgroundImage (weakreference, picker[type='image']) < jmix:image
+```
+
+**Never use `< 'jnt:file'`** (quoted string form) — it does not enforce image type correctly.
+
+**Never declare `imageAlt (string) i18n`** alongside an image weakreference. The referenced image node already has `jcr:title` (from `mix:title`). Use that as the alt text in the view:
+
+```tsx
+const imageAlt = props.image?.getPropertyAsString("jcr:title") ?? "";
+```
+
+Remove any `imageAlt` property — it forces editors to enter duplicate data.
+
+### `jmix:droppableContent` — never extend directly
+
+Always define a module-level component mixin and extend that:
+
+```cnd
+// In settings/definitions.cnd
+[nsmix:component] > jmix:droppableContent, jmix:accessControllableContent mixin
+```
+
+Then all component types extend `nsmix:component`.
+
+### `jmix:hiddenType` — hide from Page Builder picker
+
+Structural/container types editors should not add manually:
+
+```cnd
+[ns:ctaContainer] > jnt:content, jmix:hiddenType orderable
+```
+
+**Never use `jmix:studioOnly`** — it causes silent rendering issues in some contexts.
+
+### `jmix:accessControllableContent` — per-component access control
+
+Add to your base module mixin so all components support it:
+
+```cnd
+[nsmix:component] > jmix:droppableContent, jmix:accessControllableContent mixin
+```
+
+### `jmix:link` — built-in link type
+
+Provides `j:linkType`, `j:linknode`, `j:url`, `j:linkTitle`. Extend this mixin as an alternative to declaring `j:linkType` directly on a type that needs only link behavior and nothing else.
+
+## picker[] selector
+
+| Selector | Use |
+|---|---|
+| `picker[type='image']` | Image assets only |
+| `picker[type='file']` | Any file asset |
+
+```cnd
+- backgroundImage (weakreference, picker[type='image']) < jmix:image
+- attachment (weakreference, picker[type='file']) < jnt:file
+```
+
+## Two-tier component mixin system
+
+If the module uses custom area types (see `jahia-dev-create-page-template`):
+
+```cnd
+[nsmix:component]     > jmix:droppableContent, jmix:accessControllableContent mixin
+[nsmix:pageComponent] > nsmix:component mixin
+```
+
+| Component will be… | Extend |
+|---|---|
+| Dropped in page areas | `nsmix:pageComponent` |
+| Child of another component | `nsmix:component` |
+| Listed programmatically | `nsmix:component` |
+
+A component extending only `nsmix:component` **cannot** be dropped in areas that use `nsmix:pageComponent`.

package/dist/claude/.claude/agents/cnd-numbers-dates.md

@@ -0,0 +1,61 @@
+# CND Numeric, Date & Boolean Properties
+
+## Types
+
+| Type | Editor widget | Notes |
+|---|---|---|
+| `long` | Integer number input | Counts, limits, columns |
+| `double` | Decimal number input | Coordinates, prices, ratios |
+| `boolean` | Checkbox | Feature flags, toggles |
+| `date` | Date picker | ISO 8601 stored, string in TypeScript |
+| `date, datepicker` | Date + time picker | Same storage, richer widget |
+
+## Default values with `autocreated`
+
+Always combine `autocreated` with `= 'value'`:
+
+```cnd
+- columns (long) = '3' autocreated mandatory < '1', '2', '3', '4'
+- isHighlighted (boolean) = 'false' autocreated
+- country (string, choicelist[country]) = 'US' autocreated mandatory
+```
+
+## Range constraints
+
+```cnd
+// Numeric range — inclusive brackets
+- latitude (double) mandatory < "[-90,90]"
+- longitude (double) mandatory < "[-180,180]"
+- rating (long) mandatory < "[1,5]"
+```
+
+**Star ratings always need a range constraint.** Never write `rating (long)` without `< "[1,5]"`:
+
+```cnd
+// WRONG
+- rating (long) = 5 indexed=no
+
+// CORRECT
+- rating (long) = '3' autocreated mandatory < "[1,5]"
+```
+
+## Date range constraints
+
+Parentheses = exclusive bound, brackets = inclusive. Leave a side empty for open-ended:
+
+```cnd
+// Any date after 2020-01-01 (exclusive)
+- eventDate (date, datepicker) < '(2020-01-01T00:00:00.000,)'
+
+// Bounded campaign window
+- campaignDate (date, datepicker) < '(2020-01-01T00:00:00.000,2030-12-31T00:00:00.000)'
+```
+
+## TypeScript mapping
+
+| CND type | TypeScript |
+|---|---|
+| `long` | `number` |
+| `double` | `number` |
+| `boolean` | `boolean` |
+| `date` | `string` (ISO 8601) |

package/dist/claude/.claude/agents/cnd-string-selectors.md

@@ -0,0 +1,94 @@
+# CND String & Selector Properties
+
+## String type variants
+
+| Type declaration | Editor widget | When to use |
+|---|---|---|
+| `(string)` | Single-line text input | Short labels, IDs, slugs |
+| `(string, textarea)` | Multi-line text area | Paragraphs, descriptions |
+| `(string, richtext)` | Rich text editor (TinyMCE) | Body content, formatted text |
+| `(string) multiple` | Tag input / list | Lists of plain strings |
+
+## Fixed-choice dropdowns
+
+Use `(string, choicelist)` + `< 'val1', 'val2'` for a dropdown with a hard-coded list.
+**Never use `choicelist[val1,val2]`** — the bracket syntax is for initializer keywords, not values.
+
+```cnd
+- difficulty (string, choicelist) i18n < 'beginner', 'intermediate', 'advanced'
+- variant (string, choicelist) < 'primary', 'secondary', 'ghost'
+```
+
+## `mix:title` instead of a title string property
+
+**NEVER write `- title (string) i18n mandatory`.**
+Extend `mix:title` instead — it adds `jcr:title`, which Jahia's UI, breadcrumbs, and search use natively.
+
+```cnd
+// ✅ Correct
+[ns:heroSection] > jnt:content, nsmix:component, mix:title
+
+// ❌ Wrong — duplicates what mix:title already provides
+[ns:heroSection] > jnt:content, nsmix:component
+ - title (string) i18n mandatory
+```
+
+Access in the view as `props["jcr:title"]`.
+
+## Link picker — `choicelist[linkTypeInitializer]`
+
+**NEVER use `(string)` for a link, URL, href, or path.**
+Use `choicelist[linkTypeInitializer]` — it renders an internal/external/none picker in the editor.
+
+**Declare ONLY `j:linkType` in the CND. Do NOT add `j:linknode` or `j:url` — Jahia injects them automatically.**
+
+```cnd
+// ✅ Correct — bare minimum
+[ns:callToAction] > jnt:content, nsmix:component
+ - label (string) i18n mandatory
+ - j:linkType (string, choicelist[linkTypeInitializer]) mandatory
+
+// ❌ Wrong — do not declare companion fields
+ - j:linknode (weakreference)   // injected by Jahia — remove this
+ - j:url (string)               // injected by Jahia — remove this
+```
+
+TypeScript discriminated union for the view:
+
+```ts
+import type { JCRNodeWrapper } from "org.jahia.services.content";
+export type Props =
+  | { label?: string; "j:linkType": "none" }
+  | { label?: string; "j:linkType": "internal"; "j:linknode"?: JCRNodeWrapper }
+  | { label?: string; "j:linkType": "external"; "j:url"?: string; "j:linkTitle"?: string };
+```
+
+In the view, switch on `props["j:linkType"]`.
+
+## Other `choicelist[...]` initializers
+
+| Initializer | What it renders |
+|---|---|
+| `choicelist[country]` | Country selector (ISO codes, localized labels) |
+| `choicelist[resourceBundle]` | Labels from `.properties` file keys |
+| `choicelist[nodes=/path;type=jnt:content]` | Nodes under a JCR path |
+| `choicelist[componentTypes=jnt:page]` | Registered views of a node type |
+| `choicelist[menus]` | Site menus |
+
+## Regex constraints on strings
+
+```cnd
+- contactEmail (string) < '^$|[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}'
+- slug (string) < '^[a-z0-9-]+$'
+- externalUrl (string) < '^https?://'
+```
+
+## Common attributes
+
+| Attribute | Meaning |
+|---|---|
+| `i18n` | Translatable per language — **default to always on user-facing fields** |
+| `mandatory` | Required |
+| `multiple` | List of values |
+| `primary` | Highlighted field in editor (one per type) |
+| `autocreated` | Auto-created on node creation — always combine with `= 'defaultValue'` |

package/dist/claude/.claude/agents/jahia-cnd-author.md

@@ -0,0 +1,130 @@
+---
+name: jahia-cnd-author
+description: Use when you need to write a Jahia CND content type definition and its TypeScript props interface. Receives a component spec and produces a per-component definition.cnd + types.ts with correct Jahia-specific syntax. Self-validates output before returning.
+allowed-tools: Read, Write, Edit, Bash
+tools:
+  Read: true
+  Write: true
+  Edit: true
+  Bash: true
+---
+
+You are a Jahia CND specialist. Your sole job is to write correct `definition.cnd` and `types.ts` files for a single component type. You have no MCP tools and should not perform content operations or deployments.
+
+## Your inputs
+
+You will receive a structured spec:
+
+```
+Component: <name>
+Namespace prefix: <ns>
+Module path: <path to module root>
+Fields:
+  - <field name>: <type description> [mandatory] [i18n] [multiple]
+Usage: <where this component appears>
+Children: <repeatable sub-items if any>
+```
+
+## Step 1 — Locate and load reference files
+
+Reference files live next to this agent file. First, discover where they are:
+
+```bash
+# Find the directory that contains the cnd-jahia-mixins reference file
+find . -maxdepth 4 -name "cnd-jahia-mixins*" 2>/dev/null | head -5
+```
+
+Then read the files you need (using whichever path the find command returned):
+
+- **Always read**: `cnd-jahia-mixins` (required — tells you which native mixins to extend)
+- **If text, link, or choice properties**: `cnd-string-selectors`
+- **If repeatable child items**: `cnd-child-nodes`
+- **If numbers, dates, or booleans**: `cnd-numbers-dates`
+
+Do not skip this step. These files contain the exact CND patterns you must use. If the find returns nothing, something is wrong with the harness installation — stop and report.
+
+## Step 2 — Resolve namespace and location
+
+```bash
+# Get namespace prefix
+grep "^<" <module-path>/settings/definitions.cnd | head -5
+
+# Check for two-tier mixin
+grep "pageComponent" <module-path>/settings/definitions.cnd
+
+# Find the right category directory
+ls <module-path>/src/components/
+```
+
+If `namespacemix:pageComponent` exists: use it for components dropped in page areas, use `namespacemix:component` for children of other components.
+
+**File locations — collocation is mandatory:**
+
+Each component type lives in its own file, next to its view. NEVER put all types in `settings/definitions.cnd`.
+
+```
+src/
+  components/
+    Sections/
+      HeroSection/
+        definition.cnd    ← one type per file, co-located here
+        default.server.tsx
+        types.ts
+    Cards/
+      TextCard/
+        definition.cnd    ← separate file per component
+        types.ts
+settings/
+  definitions.cnd          ← namespace declarations + shared mixins ONLY
+```
+
+## Step 3 — Write the CND
+
+Create `<module-path>/src/components/<Category>/<Name>/definition.cnd`.
+
+Rules from the reference files you loaded — apply all of them:
+1. **Links**: `j:linkType (string, choicelist[linkTypeInitializer]) mandatory` — never `(string)` for `*Url`, `*Href`, `*Link`
+2. **Titles**: extend `mix:title` — never `- title (string)` or `- jcr:title (string)`
+3. **Repeatable CTAs**: child nodes `+ * (ns:callToAction)` — never flat `ctaText + ctaUrl` on the parent
+4. **Images**: `(weakreference, picker[type='image']) < jmix:image` — never `(string)` for image URLs
+5. **i18n**: on every user-facing string/textarea/richtext property
+6. **Component mixin**: extend `namespacemix:component` or `namespacemix:pageComponent` — never `jmix:droppableContent` directly on a concrete type
+
+Each per-component `definition.cnd` must include the namespace declarations at the top:
+```cnd
+<ns = 'http://...'>
+<nsmix = 'http://...'>
+```
+
+## Step 4 — Write types.ts
+
+Create `<module-path>/src/components/<Category>/<Name>/types.ts`. All fields use `?:` even if mandatory in CND.
+
+For `j:linkType` properties, use the discriminated union from the reference file you loaded.
+
+## Step 5 — Self-validate
+
+```bash
+CND=<module-path>/src/components/<Category>/<Name>/definition.cnd
+
+# Error: raw string for a link/URL property
+grep -En "^[[:space:]]*-[[:space:]]+[a-zA-Z]*(Url|Href|Link)[[:space:]]+\(string" "$CND"
+
+# Error: title declared as raw property instead of mix:title
+grep -En "^[[:space:]]*-[[:space:]]+(title|jcr:title)[[:space:]]+\(string" "$CND"
+
+# Error: concrete type extends jmix:droppableContent directly
+grep -n "jmix:droppableContent" "$CND" | grep -v "mixin"
+
+# Error: image as plain string URL
+grep -En "^[[:space:]]*-[[:space:]]+[a-zA-Z]*(Image|Photo|Avatar|Logo)[[:space:]]+\(string" "$CND"
+```
+
+If any of these print matches, fix the issue and re-run before reporting.
+
+## Step 6 — Report
+
+- Files written: paths
+- Type name(s) defined
+- Self-validate result: PASS / fixed N errors
+- Any warnings not fixed and why