@jahia/agentic 0.4.1 → 0.5.1

package/dist/kiro/.kiro/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/kiro/.kiro/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/kiro/.kiro/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/kiro/.kiro/skills/jahia-dev-accessibility/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: jahia-dev-accessibility
+description: Audits a site for accessibility issues
+argument-hint: "[live page]"
+---
+
+Run `npx pa11y [live page]` on all live pages to audit a site for accessibility issues.
+
+Fix all issues systematically, and re-run the audit until no issues remain.
+
+If available, use a subagent to fix issues, with the right amount of context.

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

@@ -0,0 +1,133 @@
+---
+name: jahia-dev-build-component
+description: Builds a complete Jahia component (content type + view + CSS) from a description. Meta-skill that orchestrates jahia-cnd-author and jahia-dev-create-view. Use when asked to build a new UI component or section.
+---
+
+## Overview
+
+This meta-skill builds a complete **Single Directory Component (SDC)** — the standard Jahia component pattern — by sequencing two atomic skills:
+
+1. `jahia-cnd-author` → create the CND definition and `types.ts`
+2. `jahia-dev-create-view` → implement the React view and CSS Module
+
+Run these steps in order. Do not skip to the view before the content type is defined.
+
+**Scale of thumbs**: a well-scoped module has 1–4 page templates, 5–10 content types, 2–5 mixins, 1–4 views per type. If a request exceeds this, split it into multiple work sessions.
+
+---
+
+## Step 0 — Optional: capture reference screenshot (interactive sessions only)
+
+If the user provides a reference URL (or mentions a site to model after), invoke `/jahia-dev-screenshot` **before writing any code** to capture the visual spec.
+
+> Skip this step in automated / autopilot contexts — screenshot comparison requires human review and adds significant time.
+
+---
+
+## Step 1 — Write the content spec
+
+Before writing any code, draft this spec internally. In an interactive session, confirm with the user; in autopilot mode, proceed with your best judgement and document what you chose:
+
+```
+Name: <ComponentName>
+Description: <What is this for? What does an editor fill in?>
+Fields:
+  - fieldName: type / i18n? / mandatory?
+  (repeat for each field)
+Views:
+  - default: <describe layout>
+  - small (optional): <compact variant>
+Used where: <Area on page / nested in <Parent> / listing item>
+Has children: <yes: ChildType / no>
+```
+
+---
+
+## Step 2 — REQUIRED: Invoke `@jahia-cnd-author`
+
+**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.
+
+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.
+
+---
+
+## Step 3 — Invoke `jahia-dev-create-view`
+
+Use the instructions from the `jahia-dev-create-view` skill to:
+
+1. Create `src/components/<Category>/<Name>/default.server.tsx`
+2. Create `src/components/<Category>/<Name>/component.module.css`
+3. Import `Props` from `./types.js`
+4. Use `buildNodeUrl`, `RenderChildren`, `RenderChild` as needed
+5. Run `yarn build && yarn jahia-deploy` to push all changes
+
+---
+
+## Step 4 — Validate
+
+1. In Jahia Page Builder, click **New content** and select the new type
+2. Fill in the content form and click **Save**
+3. Verify the component renders correctly on the page
+4. Check for the error `No rendering set for node: <type>` — if seen, re-run `yarn build && yarn jahia-deploy`
+
+---
+
+## SDC structure summary
+
+After following this skill, the component should look like:
+
+```
+src/components/<Category>/<Name>/
+├── definition.cnd        # Content type definition
+├── types.ts              # TypeScript Props interface
+├── default.server.tsx    # Default React view
+└── component.module.css  # CSS Module styles
+```
+
+Optional additions:
+- `small.server.tsx` — named view (compact/alternate rendering)
+- `<name>.client.tsx` — client-side interactive component
+
+---
+
+## Nested components
+
+If the component has child nodes (e.g. a hero with CTA buttons), repeat Steps 2–4 for each child type, then:
+
+1. Add `+ * (namespace:childType)` to the parent's `definition.cnd`
+2. Add `<RenderChildren />` to the parent's view where children should appear
+
+---
+
+## Troubleshooting
+> https://academy.jahia.com/tutorials-get-started/front-end-developer/making-a-hero-section
+
+## References
+
+- Preparing for i18n: https://academy.jahia.com/documentation/jahia-cms/jahia-8-2/developer/javascript-module-development/preparing-for-internationalization-i18n
+
+---
+
+## Validation checklist
+- [ ] Spec written before any code
+- [ ] Component count within scale of thumbs (1–4 templates, 5–10 types, 2–5 mixins, 1–4 views/type)
+- [ ] `definition.cnd` created with correct namespace and mixins
+- [ ] `types.ts` reflects all CND properties
+- [ ] `default.server.tsx` renders without errors
+- [ ] Views handle null/missing fields gracefully (mandatory does not guarantee a value at runtime)
+- [ ] `component.module.css` applied and visible
+- [ ] Semantic HTML used: correct heading level, `alt` text on images, sufficient colour contrast
+- [ ] Component appears in Page Builder content picker
+- [ ] Content can be created and renders on the page