@jahia/agentic 0.4.1 → 0.5.0

package/dist/antigravity/AGENTS.md

@@ -0,0 +1,62 @@
+# AGENTS.md
+<!-- Generated by APM CLI from distributed .apm/ primitives -->
+<!-- Build ID: f8784ff296c9 -->
+<!-- APM Version: 0.21.0 -->
+
+## Global Instructions
+
+# Jahia JavaScript Module Development
+
+## Context
+
+You are helping develop a **Jahia JavaScript Module** — a React-based template set for Jahia 8+. The module renders content from Jahia's JCR (Java Content Repository) using server-side React components (`.server.tsx`) and optional client-side islands (`.client.tsx`). Content is modelled in CND files, managed via Page Builder or jContent, and queried with JCR-SQL2 or GraphQL.
+
+## Agent Principles
+
+1. **Always invoke a skill before any Jahia task** — skills are the canonical source of patterns, gotchas, and API syntax. Never operate from memory alone.
+1a. **Always load CND reference files before writing any CND** — Jahia-specific patterns (`choicelist[linkTypeInitializer]`, `mix:title`, child nodes for CTAs, `jmix:image` weakreferences) are not in your training data. Before writing any CND, read the reference files: `find . -maxdepth 4 -name 'cnd-jahia-mixins*' | head -3`. When working interactively through skill chains, prefer `@jahia-cnd-author` (it loads these files for you).
+2. **Never use `yarn dev` from an agent** — it is an interactive file watcher for human developers only. Always deploy with `yarn build && yarn jahia-deploy` (one-shot, non-interactive).
+2a. **Use the TypeScript LSP for API discovery, never grep.** When you need to know a function's signature or what a module exports, call `mcp__ide__getDiagnostics` on the file after writing it — the LSP reads live type definitions and reports mismatches, wrong argument counts, and missing exports. Never run `grep` on `node_modules` to find a function name or signature.
+3. **Never hardcode URLs** — all navigable links must come from contributed content (JCR nodes, `j:linkType`, `buildNodeUrl`). This is a CMS: content owns the URLs.
+4. **Never use `j:linkType: "external"` for internal pages** — use `"internal"` + `j:linknode`. External URLs break on environment changes, language switches, and vanity URL rewrites.
+5. **Always verify before creating** — check that content types are deployed, site keys are correct, and parent area nodes exist before creating content via MCP.
+6. **All props are optional at runtime** — even mandatory CND fields. Always guard against `undefined` in views.
+7. **Use MCP tools for all Jahia operations — never GraphQL curl.** The `jahia` MCP server covers site, page, content, and publication operations. Never fall back to `curl` + GraphQL mutations for anything the MCP server can do. Never write Python scripts — use JavaScript or bash only.
+7a. **`yarn` and `npx` must be run from the module root** — the module is a standalone project, not part of a monorepo. Running `yarn` from a parent directory fails with a workspace boundary error. Always `cd` to the module directory first.
+7b. **Use `grep`, not `ugrep`** — `ugrep` is not available on all systems and does not support the same regex syntax. Use `grep -rn` for plain text, `grep -rn -E` for extended regex, or `grep -rn -P` for Perl-compatible patterns (e.g. lookaheads). Never use `ugrep` or `(?m)` flags.
+8. **Build accessible HTML from the start** — every view must use semantic HTML (`<main>`, `<header>`, `<nav>`, `<footer>`, `<section>`, `<article>`), include exactly one `<h1>` per page (in the template from `jcr:title` — never inside a component), use a strict heading hierarchy (h1 in template → h2 in components → h3 for sub-items), add `alt` text to every `<img>` with a meaningful fallback (`imageAlt || title || 'Image'` — never empty string), ensure sufficient colour contrast (≥ 4.5:1 for body text), include a skip link at the top of the template, and never leave a landmark (`<nav>`, `<footer>`) empty.
+9. **Review quality after each deploy** — after deploying and populating content, run `/jahia-dev-site-review` to get a scored a11y + SEO report. Fix any critical/serious violations before moving on. Do not write `pages.json` until the review passes.
+10. **Deploy iteratively** — deploy after each component with `yarn build && yarn jahia-deploy`, verify it renders, then move to the next. Don't accumulate components before deploying; a broken component is easier to diagnose in isolation.
+11. **Collocate everything per component** — each component lives in `src/components/<Category>/<Name>/` containing its `definition.cnd`, `default.server.tsx`, `component.module.css`, and `types.ts`. Never centralize content types in `settings/definitions.cnd` — that file holds only namespace declarations and the module base mixin.
+12. **Always build a page template first** — every website needs a root template at `src/templates/<ModuleName>Template/default.server.tsx`. It must include: a skip link, a `<nav>` built inline from children of the site's home node using `getChildNodes(renderContext.getSite().getNode('home'), -1, 0, n => n.isNodeType('jnt:page'))` (pages live under `home`, not directly under the site), a `<main id="main-content">` with `<h1>{title}</h1>` and Areas, and a `<footer>` that is never empty. The `<title>` tag must be `{title} | {siteName}` — never set `jcr:title` to the full `Page | Site` string; `jcr:title` is always just the short page name (e.g. "Car Insurance"). Build and deploy before any page-specific components.
+13. **SEO baseline** — every page template must render a `<title>` tag, all `<img>` must have descriptive `alt` text, all links must have visible text (no icon-only links without `aria-label`), and pages must have a single `<h1>` matching the page title.
+
+## Canonical References
+
+Always fetch these when uncertain about version-sensitive topics:
+
+| Topic | URL |
+|-------|-----|
+| Getting started / dev environment | https://academy.jahia.com/tutorials-get-started/front-end-developer/setting-up-your-dev-environment |
+| Hero section tutorial | https://academy.jahia.com/tutorials-get-started/front-end-developer/making-a-hero-section |
+| Blog / content listing | https://academy.jahia.com/tutorials-get-started/front-end-developer/making-a-blog |
+| Page templates | https://academy.jahia.com/tutorials-get-started/front-end-developer/the-about-us-page |
+| i18n (CND attribute, useTranslation, language switcher) | https://academy.jahia.com/documentation/jahia-cms/jahia-8-2/developer/javascript-module-development/preparing-for-internationalization-i18n |
+| GraphQL API | https://academy.jahia.com/documentation/developer/jahia/8/api-documentation/graphql-api |
+| Native Jahia mixins & node types | https://github.com/Jahia/jahia/tree/master/war/src/main/webapp/WEB-INF/etc/repository/nodetypes |
+| JavaScript modules monorepo | https://github.com/Jahia/javascript-modules |
+| Developer training | https://github.com/Jahia/developer-training/blob/main/js-training/slides.md |
+| Integration best practices | https://github.com/Jahia/gautier-braindump/blob/main/articles/integration-best-practices/README.md |
+
+## Local Development URLs
+
+When Jahia is running at `http://localhost:8080` (default credentials: `root` / `root1234`):
+
+- **Login**: http://localhost:8080/cms/login
+- **GraphQL playground**: http://localhost:8080/modules/graphql-dxm-provider/tools/graphql-workspace.jsp
+- **JCR browser**: http://localhost:8080/modules/tools/jcrBrowser.jsp
+- **Definitions browser**: http://localhost:8080/modules/tools/definitionsBrowser.jsp
+
+---
+*This file was generated by APM CLI. Do not edit manually.*
+*To regenerate: `apm compile`*

package/dist/claude/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "jahia": {
+      "type": "http",
+      "url": "http://localhost:8080/modules/mcp",
+      "headers": {
+        "Authorization": "Basic cm9vdDpyb290MTIzNA=="
+      }
+    }
+  }
+}

package/dist/cursor/.cursor/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "jahia": {
+      "type": "http",
+      "url": "http://localhost:8080/modules/mcp",
+      "headers": {
+        "Authorization": "Basic cm9vdDpyb290MTIzNA=="
+      }
+    }
+  }
+}

package/dist/gemini/.gemini/settings.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "jahia": {
+      "httpUrl": "http://localhost:8080/modules/mcp",
+      "headers": {
+        "Authorization": "Basic cm9vdDpyb290MTIzNA=="
+      }
+    }
+  }
+}

package/dist/index.js

@@ -861,11 +861,13 @@ ${Nt}${r.trimStart()}`), s = 3 + stripVTControlCharacters(r.trimStart()).length)
 //#endregion
 //#region cli/index.ts
 const targets = [
+	"antigravity",
 	"claude",
 	"copilot",
 	"cursor",
 	"codex",
 	"gemini",
+	"kiro",
 	"opencode",
 	"windsurf"
 ];
@@ -888,6 +890,11 @@ if (!target) {
 	target = await xe({
 		message: "Which agent do you use?",
 		options: [
+			{
+				value: "antigravity",
+				label: "Antigravity",
+				hint: "Will create AGENTS.md and .agents/"
+			},
 			{
 				value: "claude",
 				label: "Claude",
@@ -913,6 +920,11 @@ if (!target) {
 				label: "Gemini",
 				hint: "Will create AGENTS.md, GEMINI.md and .agents/"
 			},
+			{
+				value: "kiro",
+				label: "Kiro",
+				hint: "Will create AGENTS.md and .kiro/"
+			},
 			{
 				value: "opencode",
 				label: "OpenCode",

package/dist/kiro/.kiro/settings/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "jahia": {
+      "url": "http://localhost:8080/modules/mcp",
+      "headers": {
+        "Authorization": "Basic cm9vdDpyb290MTIzNA=="
+      }
+    }
+  }
+}

package/dist/kiro/.kiro/skills/jahia-cnd-author/SKILL.md

@@ -0,0 +1,94 @@
+---
+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 definition.cnd + types.ts + .properties labels with correct Jahia-specific syntax. Self-validates output before returning.
+context: fork
+argument-hint: "[business need]"
+---
+
+You are a Jahia content modeling specialist. You receive a business need, e.g. "I want to model a blog post". If used in interactive mode, you may ask for clarifications. Your job is to write correct `definition.cnd`, `types.ts`, and `.properties` files for Jahia components.
+
+## Content Modeling 101
+
+Jahia stores content in a tree structure. Each content node can define props (attached to the node itself) and child nodes (attached to the node as children). To reduce duplication, all nodes extend exactly one node type (usually `jnt:content`) and as many mixins as needed. Mixins are reusable sets of props and child nodes. Jahia ships with many native mixins, and you can define your own.
+
+The content model is pushed to Jahia as CND files. The content is displayed with JS and therefore requires a TypeScript interface for each node type. For each component, you need to provide a `definition.cnd` and a `types.ts` file.
+
+Unless told otherwise, the practice is to create one component per file, colocated with the type definition: `src/components/<name>/definition.cnd` and `./types.ts`.
+
+Project-wide mixins are declared in `settings/definitions.cnd`. Read this file first to see which mixins are already defined. Unless told otherwise, in an existing project, read all existing `.cnd` files to infer practices. When doing so, share a concise summary of your findings with the user and ask for confirmation before proceeding.
+
+## Step 1: establish the component requirements
+
+Understanding the needs correctly is mandatory to provide a good editing experience. The component may be contributed directly in pages, with the visual editor named Page Builder, or from content folders (content collections).
+
+If invoked as a sub-agent with a structured spec, skip to Step 2.
+
+In interactive mode, ask the user to confirm using this template:
+
+```
+Component: [PascalCase name]
+Description: [what it represents and how editors use it]
+Fields:
+  - name: type / i18n? / mandatory?
+Views: [default, card, fullPage, small — list all needed]
+Used where: [page area / content folder / child of <Parent>]
+Has repeatable children: [no / yes: describe them]
+```
+
+For decisions that aren't obvious — semantic vs. generic type, weakreference vs. child nodes, whether to extract a mixin — load [references/cnd-modeling-decisions.md].
+
+## Step 2: survey the project
+
+Before writing anything, understand the project context:
+
+```bash
+grep -h "^<" settings/definitions.cnd | head -1                             # namespace prefix
+grep "nsmix:pageComponent" settings/definitions.cnd                         # two-tier mixin?
+grep -rh "^\[" settings/definitions.cnd src/components/ 2>/dev/null | sort  # existing types
+```
+
+Note the namespace prefix. Check whether `nsmix:pageComponent` is declared — this means components dropped in page areas must extend `nsmix:pageComponent` rather than just `nsmix:component`. Share a concise summary of your findings and, in interactive sessions, ask for confirmation before writing.
+
+## Step 3: write `definition.cnd`
+
+Load reference files as needed for the syntax you require:
+
+- **File structure, namespace declarations, property anatomy** → [references/cnd-syntax.md]
+- **Which Jahia native mixins to extend** (`mix:title`, `jmix:mainResource`, etc.) → [references/cnd-jahia-mixins.md]
+- **String properties, choicelists, link pickers, richtext** → [references/cnd-string-selectors.md]
+- **Numeric, boolean, and date properties** → [references/cnd-numbers-dates.md]
+- **Child nodes, CTAs, orderable containers** → [references/cnd-child-nodes.md]
+- **Custom area types** (only relevant for page template types) → [references/cnd-area-types.md]
+
+Write component-level definitions to `src/components/<Category>/<Name>/definition.cnd`. Module-level mixins belong in `settings/definitions.cnd`.
+
+## Step 4: write `types.ts`
+
+Every CND property needs a corresponding TypeScript entry. Load [references/types-ts-mapping.md] for the full mapping rules, including the discriminated union pattern required for `j:linkType` properties.
+
+Write to `src/components/<Category>/<Name>/types.ts`.
+
+## Step 5: write `.properties` labels
+
+Editors see these labels in the content editor — every type name and every field needs an entry. Load [references/cnd-authoring-experience.md] for the naming conventions and icon patterns.
+
+Write to:
+- `settings/resources/<module>_en.properties`
+- `settings/resources/<module>_fr.properties` (use the English label as a placeholder if no translation is available)
+
+## Step 6: validate and report
+
+Before returning, verify:
+
+- [ ] Namespace prefix matches `settings/definitions.cnd`
+- [ ] All component types extend `nsmix:component` (or `nsmix:pageComponent` if page-area only)
+- [ ] No `- title (string) i18n mandatory` — use `mix:title` instead
+- [ ] No `imageAlt (string)` — the image node's `jcr:title` serves as alt text
+- [ ] Links use `choicelist[linkTypeInitializer]`, not a plain string
+- [ ] No declared `j:linknode` or `j:url` — Jahia injects these automatically
+- [ ] Every `autocreated` property has a `= 'value'` default
+- [ ] `jmix:hiddenType` used for structural types (never `jmix:studioOnly`)
+- [ ] Every CND property has a matching entry in `types.ts`
+- [ ] `.properties` labels written for every type and field
+
+Return **PASS** or **FAIL** with a list of specific issues.

package/dist/kiro/.kiro/skills/jahia-cnd-author/references/cnd-area-types.md

@@ -0,0 +1,55 @@
+# CND Area Types — Quick Reference
+
+## Two-tier mixin system
+
+Define in `settings/definitions.cnd`:
+
+```cnd
+[nsmix:component]     > jmix:droppableContent, jmix:accessControllableContent mixin
+[nsmix:pageComponent] > nsmix:component mixin
+```
+
+| Component placement | Extend |
+|---|---|
+| Dropped in page areas (top-level) | `nsmix:pageComponent` |
+| Child of another component | `nsmix:component` |
+
+A component extending only `nsmix:component` cannot be dropped in areas that restrict to `nsmix:pageComponent`.
+
+## Custom area type
+
+Restricts what editors can drop into a given area:
+
+```cnd
+[nsnt:pageArea] > jnt:content, jmix:list, jmix:studioOnly orderable
+ + * (nsmix:pageComponent)
+```
+
+Use in a page template view:
+
+```tsx
+<Area name="main" nodeType="nsnt:pageArea" />
+```
+
+`jmix:studioOnly` on the area type prevents it from appearing in the content picker. Use `jmix:hiddenType` for regular component types that should be hidden.
+
+## Escape hatch component
+
+One component that accepts any droppable content, for advanced editors:
+
+```cnd
+[nsnt:contentStack] > jnt:content, nsmix:pageComponent
+ + * (jmix:droppableContent)
+```
+
+Editors add this to a page area, then drop any content type inside it.
+
+## Page templates vs sectioning components
+
+| Page templates | Sectioning components |
+|---|---|
+| Fixed vertical sections per template | Editor builds sections freely |
+| Simpler for less experienced editors | More flexible, preferred for evolving integrations |
+| Use when mockups define clear distinct layouts | Use for a single free-form template |
+
+Reuse area names across templates (e.g. always `main` and `sidebar`) so content is not lost when editors switch templates.

package/dist/kiro/.kiro/skills/jahia-cnd-author/references/cnd-authoring-experience.md

@@ -0,0 +1,92 @@
+# CND Authoring Experience Reference
+
+## .properties labels and icons
+
+Required files for every content type:
+- `settings/resources/<module>_en.properties`
+- `settings/resources/<module>_fr.properties`
+
+```ini
+# Node type label
+ns_heroSection.label=Hero Section
+
+# Field labels
+ns_heroSection.subtitle.label=Subtitle
+ns_heroSection.backgroundImage.label=Background Image
+
+# Field tooltip
+ns_heroSection.subtitle.ui.tooltip=Optional subtitle text displayed below the heading.
+
+# Choicelist item labels (for resourceBundle choicelist)
+ns_heroSection.variant.primary=Primary
+ns_heroSection.variant.secondary=Secondary
+```
+
+Icon file: `settings/content-types-icons/<ns>_<typeName>.png`
+Free icons: https://www.flaticon.com/
+
+**Rules:**
+- Every node type must have a `.label` entry.
+- Every field must have a `.label` entry.
+- Choicelist options using `resourceBundle` must have a label per value.
+- Replace special characters (e.g. `:`) with `_` in the `.properties` key.
+
+---
+
+## Editor hints in views
+
+Use `renderContext.isEditMode()` to show a flat, non-interactive layout and hints in edit mode.
+
+```tsx
+({ slides }: Props, { renderContext }) => {
+  const isEdit = renderContext.isEditMode();
+  return isEdit ? (
+    <div>
+      <RenderChildren />
+      <p className={classes.hint}>Carousel — add or reorder slides here</p>
+    </div>
+  ) : (
+    <div className={classes.carousel}><RenderChildren /></div>
+  );
+};
+```
+
+Show inline validation hints:
+
+```tsx
+{renderContext.isEditMode() && value % 2 !== 0 && (
+  <p className="editor-hint">Value should be even for best visual result.</p>
+)}
+```
+
+---
+
+## import.xml recommendations
+
+Provide `import.xml` in every template set to pre-populate new sites:
+
+- A homepage with `j:isHomePage="true"` — required for sitemap and nav generation.
+- Offline folder structure with `jmix:systemNameReadonly` + `jmix:nolive`:
+  - "Offline pages/Models"
+  - "Offline pages/Drafts"
+  - "Offline pages/Archive"
+- Content folders matching your types (e.g. "Blog/Authors", "Blog/Posts").
+- Content restrictions on folders:
+  ```xml
+  jcr:mixinTypes="jmix:contributeMode" j:contributeTypes="ns:blogPost"
+  ```
+
+> `import.xml` only applies at site creation — changes do NOT update existing sites.
+
+---
+
+## jmix:visibleInContentTree
+
+Enables Page Builder visual editing inside content folders (not just list view).
+
+```cnd
+[ns:authorCollection] > jnt:content, jmix:visibleInContentTree
+ + * (ns:author)
+```
+
+Use when editors benefit from visual layout while editing content folder items.

package/dist/kiro/.kiro/skills/jahia-cnd-author/references/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.