@jahia/agentic 0.3.0 → 0.4.1

package/dist/cursor/.agents/skills/jahia-cnd-author/references/cnd-string-selectors.md

@@ -0,0 +1,133 @@
+# 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 |
+| `(string, tag[autocomplete=<n>,separator='<char>']) multiple` | Tag input with autocomplete | Tagging, keywords |
+| `(string, color)` | Color picker | Color values |
+| `(string, cron)` | Cron expression editor | Scheduling |
+
+## 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'
+```
+
+## `choicelist[...]` initializer variants
+
+| Initializer | What it renders |
+|---|---|
+| `choicelist` | Dropdown from constraints list |
+| `choicelist[componentTypes='<types>']` | Component types/mixins dropdown |
+| `choicelist[country]` | Countries list (ISO codes, localized labels) |
+| `choicelist[menus]` | Site menus |
+| `choicelist[nodes='<path>;<type>;<property>']` | Nodes from a JCR path; supports `$currentSiteTemplatesSet` |
+| `choicelist[nodetypes='<type>']` | Node types inheriting from `<type>`; special values: `PRIMARY;fromDependencies;useName`, `MIXIN;fromDependencies;useName` |
+| `choicelist[permissions]` | Permissions list |
+| `choicelist[renderModes]` | Render modes |
+| `choicelist[resourceBundle]` | Keys as constraints, labels from resource bundle |
+| `choicelist[sortableFieldnames]` | Sortable field names |
+| `choicelist[subnodetypes='<type>']` | Similar to nodetypes |
+| `choicelist[templates]` | Site templates; variants: `mainresource`, `reference`, `subnodes`, `<type>`, with optional `, dependentProperties='<property>'` |
+| `choicelist[templatesNode]` | Node templates; variant: `pageTemplate` |
+| `choicelist[workflow]` | Available workflows |
+| `choicelist[linkTypeInitializer]` | Internal/external/none link picker (see below) |
+
+## `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"]`.
+
+## Weakreference picker variants
+
+| Initializer | What it picks |
+|---|---|
+| `picker[type='image']` | Image from media library |
+| `picker[type='editoriallink']` | Editorial content node |
+| `picker[type='page']` | Page node |
+| `picker[type='file']` | Any file asset |
+
+## 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?://'
+```
+
+## Modifiers / keywords
+
+| Keyword | Description |
+|---|---|
+| `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; requires `= 'value'` |
+| `indexed=no` | Excludes from indexing |
+| `nofulltext` | Excludes from full-text search |
+| `boost=<float>` | Multiplies full-text search score |
+| `facetable` | Enables faceted search on this property |
+| `protected` | Cannot be set by external tools |
+| `hidden` | Hidden in editor |
+
+## Examples combining selectors and modifiers
+
+```cnd
+- tags (string, tag[autocomplete=5,separator=',']) multiple
+- color (string, color) = '#000000' autocreated
+- template (string, choicelist[templates]) i18n
+- nodes (weakreference, choicelist[nodes='/sites/systemsite/categories;jnt:category',sort]) multiple
+- image (weakreference, picker[type='image'])
+- page (weakreference, picker[type='page'])
+```

package/dist/cursor/.agents/skills/jahia-cnd-author/references/cnd-syntax.md

@@ -0,0 +1,119 @@
+# CND Syntax Reference
+
+## Namespace declarations
+
+| Pattern | Example |
+|---|---|
+| `<prefix = 'uri'>` | `<jnt = 'http://www.jahia.org/jahia/nt/1.0'>` |
+
+Jahia built-in namespaces:
+
+| Prefix | URI |
+|---|---|
+| `j` | `http://www.jahia.org/jahia/1.0` |
+| `jnt` | `http://www.jahia.org/jahia/nt/1.0` |
+| `jmix` | `http://www.jahia.org/jahia/mix/1.0` |
+
+Module convention: declare two namespaces — one for node types (`ns`), one for mixins (`nsmix`). The prefix is read from the first `<…>` line in `settings/definitions.cnd`.
+
+---
+
+## Node type definition
+
+```cnd
+[ns:nodeType] > ns:baseType, nsmix:mixin1, nsmix:mixin2
+ - property1 (type) = 'default' modifier1 modifier2
+ + childNode1 (ns:childType)
+```
+
+Add `abstract` after supertypes to prevent direct instantiation:
+
+```cnd
+[ns:abstractType] > jnt:content abstract
+```
+
+All component node types must extend `nsmix:component`:
+
+```cnd
+[ns:myComponent] > jnt:content, nsmix:component
+```
+
+---
+
+## Mixin definition
+
+```cnd
+[nsmix:myMixin] > jmix:templateMixin mixin
+ - property1 (type) = 'default'
+```
+
+---
+
+## Property anatomy
+
+```
+- propertyName (type, visualHint) = 'default' modifier1 modifier2 < constraint1, constraint2
+```
+
+| Part | Position | Example |
+|---|---|---|
+| Name | after `-` | `- title` |
+| Type | first parens | `(string)` |
+| Visual hint | after type, same parens | `(string, text)` |
+| Default value | after `=` | `= 'Hello'` |
+| Modifiers | after default | `i18n mandatory multiple autocreated primary` |
+| Constraints | after `<` | `< 'en', 'fr', 'de'` |
+
+### Property types
+
+| Type | Notes |
+|---|---|
+| `string` | Plain text |
+| `richtext` | HTML rich text |
+| `boolean` | `true` / `false` |
+| `long` | Integer |
+| `double` | Floating point |
+| `decimal` | Exact decimal |
+| `date` | ISO date/time |
+| `weakreference` | Node reference |
+| `uri` | URI string |
+
+### Common modifiers
+
+| Modifier | Meaning |
+|---|---|
+| `i18n` | Translatable per language |
+| `mandatory` | Must have a value |
+| `multiple` | Multi-value property |
+| `autocreated` | Created automatically |
+| `primary` | Primary property of the node |
+| `hidden` | Not shown in editor UI |
+| `protected` | Not editable by users |
+
+### Common visual hints
+
+| Hint | Editor widget |
+|---|---|
+| `text` | Single-line text |
+| `textarea` | Multi-line text |
+| `richtext` | Rich text editor |
+| `picker` | Content picker |
+| `color` | Color picker |
+| `checkbox` | Checkbox |
+| `radio` | Radio buttons |
+| `choicelist` | Drop-down list |
+
+---
+
+## Minimal working example
+
+```cnd
+<ns = 'http://www.example.org/ns/1.0'>
+<nsmix = 'http://www.example.org/nsmix/1.0'>
+
+[ns:card] > jnt:content, nsmix:component
+ - title (string, text) = '' i18n
+ - body (string, richtext) i18n
+ - ctaLabel (string, text) i18n
+ - ctaLink (weakreference, picker[type='page'])
+```

package/dist/cursor/.agents/skills/jahia-cnd-author/references/types-ts-mapping.md

@@ -0,0 +1,73 @@
+## CND type → TypeScript mapping
+
+| CND type | TypeScript type | Notes |
+|---|---|---|
+| `string` | `string` | |
+| `string` + `multiple` | `string[]` | |
+| `long` | `number` | 64-bit integer |
+| `double` | `number` | 64-bit float |
+| `boolean` | `boolean` | |
+| `date` | `string` | ISO 8601 string |
+| `weakreference` | `JCRNodeWrapper \| undefined` | Always optional |
+| `weakreference` + `multiple` | `JCRNodeWrapper[]` | |
+
+## Required import
+```ts
+import type { JCRNodeWrapper } from "org.jahia.services.content";
+```
+
+## mix:title
+When a type extends `mix:title`, add `"jcr:title"?: string` to Props.
+
+## linkTypeInitializer discriminated union
+When CND has `j:linkType (string, choicelist[linkTypeInitializer])`, use a discriminated union:
+```ts
+export type Props =
+  | { "j:linkType": "none" }
+  | { "j:linkType": "internal"; "j:linknode"?: JCRNodeWrapper }
+  | { "j:linkType": "external"; "j:url"?: string; "j:linkTitle"?: string };
+```
+Add other fields of the type to each union member.
+
+## Choicelist (fixed values)
+Use a string literal union:
+```ts
+variant?: "primary" | "secondary" | "ghost";
+columns?: "1" | "2" | "3";   // long choicelist values come through as strings
+```
+
+## Full example
+For a CND type:
+```cnd
+[ns:card] > jnt:content, nsmix:component, mix:title
+ - subtitle (string) i18n
+ - body (string, richtext) i18n
+ - image (weakreference, picker[type='image']) < jmix:image
+ - variant (string, choicelist) < 'primary', 'secondary'
+ - j:linkType (string, choicelist[linkTypeInitializer]) mandatory
+```
+
+The `types.ts`:
+```ts
+import type { JCRNodeWrapper } from "org.jahia.services.content";
+
+type CardBase = {
+  "jcr:title"?: string;
+  subtitle?: string;
+  body?: string;
+  image?: JCRNodeWrapper;
+  variant?: "primary" | "secondary";
+};
+
+export type Props = CardBase & (
+  | { "j:linkType": "none" }
+  | { "j:linkType": "internal"; "j:linknode"?: JCRNodeWrapper }
+  | { "j:linkType": "external"; "j:url"?: string; "j:linkTitle"?: string }
+);
+```
+
+## Rules
+- All properties are optional unless `mandatory` in CND (and even mandatory fields may be absent at runtime — always guard)
+- `weakreference` is always `JCRNodeWrapper | undefined` regardless of `mandatory`
+- Never add `j:linknode` or `j:url` to the CND — they appear in types.ts via the discriminated union because Jahia injects them
+- `i18n` does not affect the TypeScript type

package/dist/cursor/.agents/skills/jahia-dev-accessibility/SKILL.md

@@ -1,271 +1,11 @@
 ---
 name: jahia-dev-accessibility
-description: Audits a Jahia JS module for WCAG 2.1 AA accessibility violations using axe-core and Playwright. Runs automated checks against all live pages, reports violations by severity, and fixes them in the React views and CSS. Invoke after building components or before final review.
-allowed-tools: Bash, Read, Write, Edit
+description: Audits a site for accessibility issues
+argument-hint: "[live page]"
 ---
 
-# Skill: jahia-dev-accessibility
+Run `npx pa11y [live page]` on all live pages to audit a site for accessibility issues.
 
-Runs a live accessibility audit against all published pages of the site, reports violations, and fixes them in the source code.
+Fix all issues systematically, and re-run the audit until no issues remain.
 
----
-
-## Step 1 — Confirm pages are live
-
-You need the list of public page URLs. Look for `pages.json` in the module root first:
-
-```bash
-cat pages.json 2>/dev/null || echo "not found"
-```
-
-If absent, derive URLs from the site structure or ask the user. All pages must be accessible at `http://localhost:8080`.
-
----
-
-## Step 2 — Install audit tooling
-
-Check if `@axe-core/playwright` and `playwright` are available:
-
-```bash
-node -e "require('@axe-core/playwright'); require('playwright'); console.log('ok')" 2>/dev/null || echo "missing"
-```
-
-If missing, install temporarily (project-local, not committed):
-
-```bash
-npm install --no-save @axe-core/playwright playwright
-npx playwright install chromium --with-deps
-```
-
----
-
-## Step 3 — Run the audit
-
-Save this script as `/tmp/a11y-audit.mjs` and run it:
-
-```js
-import { chromium } from "playwright";
-import { AxeBuilder } from "@axe-core/playwright";
-import { readFileSync } from "fs";
-
-const urls = JSON.parse(readFileSync("pages.json", "utf-8"));
-
-const browser = await chromium.launch({ args: ["--no-sandbox"] });
-const page = await browser.newPage();
-
-for (const url of urls) {
-  console.log(`\n${"=".repeat(60)}\nAuditing: ${url}\n${"=".repeat(60)}`);
-  await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
-
-  const results = await new AxeBuilder({ page })
-    .withTags(["wcag2a", "wcag2aa", "wcag21aa"])
-    .analyze();
-
-  if (results.violations.length === 0) {
-    console.log("✅ No violations found.");
-    continue;
-  }
-
-  for (const v of results.violations) {
-    console.log(`\n[${v.impact?.toUpperCase()}] ${v.id}: ${v.description}`);
-    console.log(`Help: ${v.helpUrl}`);
-    for (const node of v.nodes) {
-      console.log(`  Target: ${node.target.join(" > ")}`);
-      console.log(`  HTML:   ${node.html}`);
-      if (node.failureSummary) {
-        console.log(`  Fix:    ${node.failureSummary}`);
-      }
-    }
-  }
-}
-
-await browser.close();
-```
-
-```bash
-node /tmp/a11y-audit.mjs 2>&1 | tee /tmp/a11y-report.txt
-```
-
----
-
-## Step 4 — Interpret results
-
-Group violations by impact. Focus on `critical` and `serious` first — they contribute most to a poor score.
-
-Common violations in Jahia JS modules and their fixes:
-
-### 🔴 Critical / Serious
-
-**`color-contrast`** — text fails WCAG AA contrast ratio (4.5:1 for normal text, 3:1 for large text)
-```css
-/* Bad */
-color: #aaa; background: #fff;
-
-/* Fix — use a contrast checker: https://webaim.org/resources/contrastchecker/ */
-color: #595959; /* 7:1 ratio on white */
-```
-
-**`image-alt`** — `<img>` missing `alt` attribute
-```tsx
-/* Bad */
-<img src={buildNodeUrl(props.image)} />
-
-/* Fix — use content from CND, fall back to empty string for decorative */
-<img src={buildNodeUrl(props.image)} alt={props.imageAlt ?? ""} />
-```
-Add `- imageAlt (string) i18n` to the CND and `imageAlt?: string` to `types.ts`.
-
-**`button-name`** — `<button>` or `<a>` is empty (icon-only without label)
-```tsx
-/* Bad */
-<button><svg>...</svg></button>
-
-/* Fix */
-<button aria-label="Open menu"><svg aria-hidden="true">...</svg></button>
-```
-
-**`landmark-one-main`** — page has no `<main>` landmark
-```tsx
-/* Fix — wrap page content in <main> */
-<main id="main-content">
-  {/* page content */}
-</main>
-```
-
-**`page-has-heading-one`** — page has no `<h1>` element
-```tsx
-/* Fix — ensure the hero or first section renders an <h1> */
-<h1>{props.title}</h1>
-```
-
-**`link-name`** — `<a>` with no accessible text
-```tsx
-/* Bad */
-<a href={url}><img src="..." /></a>
-
-/* Fix */
-<a href={url}><img src="..." alt={props.linkLabel ?? "Learn more"} /></a>
-```
-
-### 🟡 Moderate
-
-**`heading-order`** — headings skip levels (e.g. `<h1>` → `<h3>`)
-```tsx
-/* Review: the first heading in a component should be h2 (after the page h1) */
-/* Section titles: h2, subsections: h3 */
-```
-
-**`region`** — content is outside landmark regions  
-Wrap page sections in semantic elements: `<header>`, `<nav>`, `<main>`, `<footer>`, `<section aria-label="...">`.
-
-**`list`** — `<ul>` or `<ol>` contains elements other than `<li>`
-```tsx
-/* Bad */
-<ul>
-  <div>item</div>
-</ul>
-
-/* Fix */
-<ul>
-  <li>item</li>
-</ul>
-```
-
-**`html-has-lang`** — `<html>` element missing `lang` attribute  
-This is set at the page template level. Verify the template registered in `src/templates/` includes `lang`:
-```tsx
-/* In the page template */
-<html lang={currentLanguage ?? "en"}>
-```
-Jahia provides the language via `useServerContext()`:
-```tsx
-import { useServerContext } from "@jahia/javascript-modules-library";
-const { currentLanguage } = useServerContext();
-```
-
-**`aria-required-children`** — ARIA role is missing required children  
-Avoid misusing ARIA roles. Prefer native HTML elements (`<ul>/<li>`, `<table>/<tr>/<td>`).
-
----
-
-## Step 5 — Fix in source
-
-For each violation:
-
-1. Identify the component: match `node.target` HTML to a `.server.tsx` file
-2. Edit the view to apply the fix
-3. If the fix requires a new CND field (e.g. `imageAlt`), update `definition.cnd` and `types.ts`
-4. Run `yarn build && yarn jahia-deploy`
-
-After all fixes:
-
-```bash
-# Re-run the audit to verify violations are resolved
-node /tmp/a11y-audit.mjs 2>&1 | grep -E "(CRITICAL|SERIOUS|MODERATE|No violations)"
-```
-
-Iterate until only `minor` violations remain (or none).
-
----
-
-## Step 6 — Proactive checks beyond axe-core
-
-axe-core catches ~30–40% of WCAG issues automatically. Also check manually:
-
-- **Keyboard navigation**: can every interactive element (link, button, form field) be reached with Tab?
-- **Focus indicators**: is `:focus` visible on all interactive elements?
-  ```css
-  /* Ensure focus ring is never suppressed globally */
-  /* Bad */
-  * { outline: none; }
-  /* Fix — use :focus-visible */
-  :focus-visible { outline: 2px solid #0969da; outline-offset: 2px; }
-  ```
-- **Skip link**: add a "Skip to main content" link as the first focusable element
-  ```tsx
-  <a href="#main-content" className={styles.skipLink}>Skip to main content</a>
-  ```
-  ```css
-  .skipLink {
-    position: absolute;
-    top: -100%;
-    left: 0;
-    background: #000;
-    color: #fff;
-    padding: 8px 16px;
-    z-index: 999;
-  }
-  .skipLink:focus { top: 0; }
-  ```
-- **Motion**: if any CSS animation exists, wrap it in `@media (prefers-reduced-motion: no-preference)`
-- **Touch targets**: interactive elements should be at least 44×44px
-
----
-
-## Step 7 — Report summary
-
-After fixing, report:
-
-```
-## Accessibility Audit Summary
-
-Pages audited: N
-Violations fixed:
-  - [critical] color-contrast: 3 instances → fixed (updated CSS contrast ratios)
-  - [serious] image-alt: 2 instances → fixed (added imageAlt CND field)
-  - [serious] button-name: 1 instance → fixed (added aria-label to icon button)
-  - [moderate] heading-order: 2 instances → fixed (restructured h2/h3 hierarchy)
-
-Remaining violations: N (all minor / informational)
-
-Axe tags checked: wcag2a, wcag2aa, wcag21aa
-```
-
----
-
-## References
-
-- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
-- axe-core rules: https://dequeuniversity.com/rules/axe/
-- WCAG 2.1 Quick Ref: https://www.w3.org/WAI/WCAG21/quickref/
-- MDN ARIA: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA
+If available, use a subagent to fix issues, with the right amount of context.

package/dist/cursor/.agents/skills/jahia-dev-build-component/SKILL.md

@@ -43,15 +43,23 @@ Has children: <yes: ChildType / no>
 
 ---
 
-## Step 2 — Invoke `jahia-dev-define-content-type`
+## Step 2 — REQUIRED: Invoke `@jahia-cnd-author`
 
-Use the instructions from the `jahia-dev-define-content-type` skill to:
+**Do not write CND manually.** Jahia-specific patterns (`choicelist[linkTypeInitializer]`, `mix:title`, child nodes for CTAs) are not in LLM training data — writing from memory produces broken output.
 
-1. Identify the namespace (check `settings/definitions.cnd`)
-2. Create `src/components/<Category>/<Name>/definition.cnd`
-3. Create `src/components/<Category>/<Name>/types.ts`
-4. Run `yarn build && yarn jahia-deploy` to push the type to Jahia
-5. Verify the content type appears in the Jahia content editor
+Invoke `@jahia-cnd-author` as a sub-agent with the complete spec:
+
+```
+Component: <PascalCase name>
+Namespace prefix: <ns>
+Module path: <absolute path to module root>
+Fields:
+  - <fieldName>: <type description> [mandatory] [i18n] [multiple]
+Children: <repeatable sub-items, e.g. "CTA buttons with label + link">
+Usage: <where this component appears, e.g. "dropped in page areas">
+```
+
+Wait for **PASS** before continuing. If it returns **FAIL**, send the issues back to `@jahia-cnd-author` to fix.
 
 ---