@jahia/agentic 0.2.0 → 0.4.0

package/dist/windsurf/.windsurf/skills/jahia-dev-query-content/SKILL.md

@@ -1,53 +1,41 @@
 ---
 name: jahia-dev-query-content
-description: Writes JCR-SQL2 queries to list and filter Jahia content. Use when asked to list articles, display content from a folder, filter by date, or build a content listing.
-allowed-tools: Bash, Read, Write, Edit, WebFetch
+description: Designs JCR-SQL2 content queries for Jahia page-builder listings and JS module views. Use when asked to list content from folders, filter items, sort results, or wire `useJCRQuery` into a template-set component.
 ---
 
-## Overview
-
-Jahia stores all content in a tree-based **Java Content Repository (JCR)**. Content can be queried using **JCR-SQL2**, a SQL-like language. This is used to build listings (blogs, news, team members, etc.) from content stored in **Content Folders**.
+# Skill: jahia-dev-query-content
 
-There are **three ways** to query content in Jahia JS modules:
-1. **No-code**: built-in `Jahia - Queries` component in Page Builder
-2. **Server-side hook**: `useJCRQuery` in a `.server.tsx` view
-3. **Client-side hook**: `useJCRQuery` in a `.client.tsx` island (for dynamic, browser-triggered queries)
+Use this skill when building content listings in Jahia template sets.
+For pure JCR-SQL2 language rules, full-text syntax, joins, pagination, and performance guardrails, also use `/jahia-jcr-sql2`.
 
 ---
 
-## Step 1 — Understand Content Folders
+## Overview
 
-Instead of placing content directly on a page, reusable content (blog posts, team members, etc.) is stored in **Content Folders** under the `contents/` tree of the site.
+Jahia stores editorial content in the JCR. In template sets, you usually query it in one of three ways:
 
-To create a content folder in Jahia UI:
-1. Open **jContent** (the content manager)
-2. Navigate to **Content Folders** in the left sidebar
-3. Right-click → **New Folder**, name it (e.g. `blog`)
-4. Create content items inside this folder
+1. **Page Builder query component** — no-code listing using a JCR query string
+2. **Server-side view** — `useJCRQuery` inside a `.server.tsx` component
+3. **Client-driven experience** — use a dedicated API strategy only when a server-side query is not enough
 
 ---
 
-## Step 2 — Use the built-in query component (no code)
+## Step 1 — Understand where content lives
 
-For simple listings, use the built-in **Jahia - Queries > Content items using JCR Query** component in Page Builder. Enter your JCR-SQL2 query in the query field.
+Reusable content usually lives under `/sites/<siteKey>/contents/...` instead of directly under pages.
+Create and manage those folders in jContent.
 
----
-
-## Step 2b — Make content folders editable in jContent
-
-Content folders are browsable via **jContent** by default, but if editors need to manage content directly from the **Content Tree** in Page Builder, add `jmix:visibleInContentTree` to the folder node type:
+If editors need the folder visible in the Page Builder content tree, add `jmix:visibleInContentTree` to the folder type:
 
 ```cnd
 [namespace:blogFolder] > jnt:contentFolder, jmix:visibleInContentTree
 ```
 
-This makes the folder appear in the left sidebar of Page Builder, enabling drag-and-drop management.
-
 ---
 
-## Step 3 — Write a JCR-SQL2 query
+## Step 2 — Start with the right SQL2 shape
 
-### Basic query — list all items of a type
+### List all items of a type under a folder
 
 ```sql
 SELECT *
@@ -55,137 +43,93 @@ FROM [namespace:typeName] AS item
 WHERE ISDESCENDANTNODE(item, '/sites/<siteKey>/contents/<folderName>')
 ```
 
-Replace `<siteKey>` with the site key set during site creation.
-
-### Filter out drafts (items without a date)
+### Only direct children of a folder
 
 ```sql
 SELECT *
 FROM [namespace:blogPost] AS post
-WHERE ISDESCENDANTNODE(post, '/sites/<siteKey>/contents/blog')
-  AND post.[publicationDate] IS NOT NULL
-ORDER BY post.[publicationDate] DESC
+WHERE ISCHILDNODE(post, '/sites/<siteKey>/contents/blog')
 ```
 
-### Query all descendants (not just direct children)
-
-Use `ISDESCENDANTNODE` for nested folder structures:
+### Filter drafts and sort newest first
 
 ```sql
--- All blog posts anywhere under /contents/blog (including subfolders)
-SELECT * FROM [namespace:blogPost] AS post
+SELECT *
+FROM [namespace:blogPost] AS post
 WHERE ISDESCENDANTNODE(post, '/sites/<siteKey>/contents/blog')
+  AND post.[publicationDate] IS NOT NULL
+ORDER BY post.[publicationDate] DESC
 ```
 
-Use `ISCHILDNODE` when you want only direct children of a folder:
-
-```sql
--- Only direct children of /contents/blog
-SELECT * FROM [namespace:blogPost] AS post
-WHERE ISCHILDNODE(post, '/sites/<siteKey>/contents/blog')
-```
-
-### Common query clauses
-
-| Clause | Usage |
-|---|---|
-| `ISDESCENDANTNODE(x, '/path')` | Filter by location in the tree |
-| `x.[prop] IS NOT NULL` | Exclude items without a property (draft filter) |
-| `x.[prop] = 'value'` | Filter by property value |
-| `ORDER BY x.[prop] DESC` | Sort descending |
-| `ORDER BY x.[prop] ASC` | Sort ascending |
-
 ---
 
-## Step 4 — Make a content type accessible at its own URL
+## Step 3 — Use the right SQL2 clauses
 
-Use `jmix:mainResource` **only** for content that needs **both a listing card AND a full detail page** (e.g. blog posts, team member profiles). Do not add it to visual composition types or navigation-only content.
+| Need | Pattern |
+|------|---------|
+| Recursive subtree | `ISDESCENDANTNODE(alias, '/path')` |
+| Direct children only | `ISCHILDNODE(alias, '/path')` |
+| Property equality | `alias.[prop] = 'value'` |
+| Pattern match | `alias.[prop] LIKE '%keyword%'` |
+| Exclude empty values | `alias.[prop] IS NOT NULL` |
+| Sort | `ORDER BY alias.[prop] DESC` |
+| Full-text | `CONTAINS(alias.*, 'term')` |
+| Relevance sort | `ORDER BY SCORE(alias) DESC` |
 
-To allow a blog post to be viewed as a full page, add `jmix:mainResource` to its CND definition:
-
-```cnd
-[namespace:blogPost] > jnt:content, mix:title, jmix:mainResource, namespacemix:component
-```
-
-Then create a full-page view for it:
-
-```tsx
-// src/components/BlogPost/fullPage.server.tsx
-// NOTE: componentType is "view" (NOT "template") — the MainResource template
-// at src/templates/MainResource/default.server.tsx routes to this view automatically
-import { jahiaComponent } from "@jahia/javascript-modules-library";
-import type { Props } from "./types.js";
-import classes from "./component.module.css";
-
-jahiaComponent(
-  {
-    componentType: "view",           // ← "view", NOT "template"
-    nodeType: "namespace:blogPost",
-    displayName: "Blog Post Full Page",
-    name: "fullPage",                // ← this name is what MainResource routes to
-  },
-  ({ "jcr:title": title, body, subtitle }: Props) => (
-    <article className={classes.article}>
-      <h1>{title}</h1>
-      <p>{subtitle}</p>
-      <div dangerouslySetInnerHTML={{ __html: body }} />
-    </article>
-  ),
-);
-```
-
-### Link to a full-page content item
-
-Use `buildNodeUrl(currentNode)` to generate the URL to the item:
-
-```tsx
-<a href={buildNodeUrl(currentNode)}>{title}</a>
-```
+**Performance rule:** always constrain queries by path.
 
 ---
 
-## Step 5 — Draft/publish pattern
+## Step 4 — Add full-text and filtering when needed
 
-A common pattern is to use a `publicationDate` property as a draft gate:
+### Phrase search sorted by relevance
 
-```cnd
-- publicationDate (date)
+```sql
+SELECT *
+FROM [namespace:blogPost] AS post
+WHERE ISDESCENDANTNODE(post, '/sites/<siteKey>/contents/blog')
+  AND CONTAINS(post.*, '"annual report"')
+ORDER BY SCORE(post) DESC
 ```
 
-Note: do **not** mark it as `mandatory` — that would be a breaking change on an existing type, and it doubles as the draft indicator (no date = draft).
-
-In the query, filter published posts only:
+### Search one property only
 
 ```sql
-AND post.[publicationDate] IS NOT NULL
+SELECT *
+FROM [namespace:blogPost] AS post
+WHERE ISDESCENDANTNODE(post, '/sites/<siteKey>/contents/blog')
+  AND CONTAINS(post.[jcr:title], 'welcome')
 ORDER BY post.[publicationDate] DESC
 ```
 
-Display the date in the view:
+### Filter by date
 
-```tsx
-{publicationDate && (
-  <time dateTime={publicationDate}>
-    {new Date(publicationDate).toLocaleDateString(
-      currentResource.getLocale().toString(),
-      { dateStyle: "long" }
-    )}
-  </time>
-)}
+```sql
+SELECT *
+FROM [namespace:blogPost] AS post
+WHERE ISDESCENDANTNODE(post, '/sites/<siteKey>/contents/blog')
+  AND post.[publicationDate] > CAST('2026-01-01T00:00:00.000Z' AS DATE)
+ORDER BY post.[publicationDate] DESC
 ```
 
+Use the millisecond form `yyyy-MM-dd'T'HH:mm:ss.SSSX` for SQL2 date casts.
+
 ---
 
-## Step 6 — Query in code with `useJCRQuery`
+## Step 5 — Use queries in Jahia UI or code
+
+### Page Builder query component
 
-For custom listing components (rather than using the built-in query component), use `useJCRQuery` from the library inside a `.server.tsx` view:
+For a simple listing, use **Jahia - Queries > Content items using JCR Query** and paste the SQL2 query there.
+
+### `useJCRQuery` in a `.server.tsx` view
 
 ```tsx
-import { jahiaComponent, useJCRQuery, Render } from "@jahia/javascript-modules-library";
-import type { JCRNodeWrapper } from "org.jahia.services.content";
+import { jahiaComponent, useJCRQuery, Render } from '@jahia/javascript-modules-library';
+import type { JCRNodeWrapper } from 'org.jahia.services.content';
 
 jahiaComponent(
-  { componentType: "view", nodeType: "namespace:blogListing" },
+  { componentType: 'view', nodeType: 'namespace:blogListing' },
   (_, { renderContext }) => {
     const siteKey = renderContext.getSite().getName();
     const posts = useJCRQuery({
@@ -206,202 +150,55 @@ jahiaComponent(
 );
 ```
 
-> `useJCRQuery` is server-side only (`.server.tsx`). For client-side dynamic queries triggered by user interaction, use the GraphQL approach in a `.client.tsx` island.
-
 ---
 
-## Step 7 — Language switcher with `getSiteLocales`
+## Step 6 — Patterns commonly needed in template sets
 
-For sites with multiple languages, build a language switcher by combining `getSiteLocales()` with `j:invalidLanguages` and `node.hasI18N()`. Filter out disabled or untranslated locales before generating URLs.
+### Make a content type renderable at its own URL
 
-```tsx
-import { getSiteLocales, buildNodeUrl, jahiaComponent } from "@jahia/javascript-modules-library";
+Use `jmix:mainResource` only for content that needs both a listing card and a full detail page.
 
-jahiaComponent(
-  { componentType: "view", nodeType: "ns:languageSwitcher" },
-  (_, { currentNode }) => {
-    const locales = getSiteLocales(); // Record<string, java.util.Locale>
-
-    // Read j:invalidLanguages (languages disabled on this node)
-    const invalidCodes = currentNode.hasProperty("j:invalidLanguages")
-      ? currentNode.getProperty("j:invalidLanguages").getValues().map((v: any) => v.getString())
-      : [];
-    const invalidSet = new Set(invalidCodes);
-
-    const links = Object.entries(locales)
-      .filter(([code, locale]) =>
-        !invalidSet.has(code) && currentNode.hasI18N(locale),
-      )
-      .map(([code]) => ({
-        code,
-        url: buildNodeUrl(currentNode, { language: code }),
-      }));
-
-    return (
-      <nav aria-label="Language switcher">
-        {links.map(({ code, url }) => (
-          <a key={code} href={url} lang={code} hrefLang={code}>
-            {code.toUpperCase()}
-          </a>
-        ))}
-      </nav>
-    );
-  },
-);
-```
-
-> `getSiteLocales()` returns all locales configured for the site — not just the active language. Always filter by `j:invalidLanguages` and `hasI18N()` before displaying.
-
----
-
-## Step 7b — Query via GraphQL with `useGQLQuery`
-
-For complex queries that span multiple nodes or need field-level projection, `useGQLQuery` is more efficient than `useJCRQuery`. It runs synchronously on the server using the current user's session.
-
-```tsx
-import { useGQLQuery, jahiaComponent } from "@jahia/javascript-modules-library";
-import { gql } from "graphql-tag";
-
-const BLOG_QUERY = gql`
-  query LatestPosts($path: String!) {
-    jcr {
-      nodeByPath(path: $path) {
-        descendants(typesFilter: { types: ["namespace:blogPost"] }, fieldFilter: {
-          filters: [{ fieldName: "publicationDate", evaluation: NOT_EMPTY }]
-        }) {
-          nodes {
-            name
-            path
-            displayName
-            property(name: "publicationDate") { value }
-            property(name: "jcr:title") { value }
-          }
-        }
-      }
-    }
-  }
-`;
-
-jahiaComponent(
-  { componentType: "view", nodeType: "namespace:blogListing" },
-  (_, { renderContext }) => {
-    const siteKey = renderContext.getSite().getName();
-    const data = useGQLQuery(BLOG_QUERY, { path: `/sites/${siteKey}/contents/blog` });
-    const posts = data?.jcr?.nodeByPath?.descendants?.nodes ?? [];
-
-    return (
-      <ul>
-        {posts.map((post: any) => (
-          <li key={post.path}>
-            <a href={post.path}>{post.property?.value ?? post.displayName}</a>
-          </li>
-        ))}
-      </ul>
-    );
-  },
-);
+```cnd
+[namespace:blogPost] > jnt:content, mix:title, jmix:mainResource, namespacemix:component
 ```
 
----
-
-## Step 8 — Hierarchical content with nested folders
-
-Content folders can be nested to create sections (e.g. `tutorials/front-end/`, `tutorials/editors/`). Use `ISDESCENDANTNODE` in queries to automatically include all levels — no query changes needed as you add sub-folders.
+Then add a `fullPage.server.tsx` view and link to the node with `buildNodeUrl(currentNode)`.
 
-For **sidebar navigation** or **tree panels**, traverse the JCR hierarchy directly instead of querying:
+### Draft gate with `publicationDate`
 
-### Get a JCR node by path
+A common pattern is:
 
-```tsx
-import { useServerContext } from "@jahia/javascript-modules-library";
-import type { JCRNodeWrapper } from "org.jahia.services.content";
-
-const { renderContext } = useServerContext();
-const folderNode = renderContext.getMainResource().getNode().getSession().getNode(
-  `/sites/${siteKey}/contents/tutorials`
-) as JCRNodeWrapper;
+```cnd
+- publicationDate (date)
 ```
 
-### Walk up to the section root
+and the query:
 
-```tsx
-function findSectionRoot(node: JCRNodeWrapper): JCRNodeWrapper {
-  const parts = node.getPath().split("/");
-  const contentsPath = parts.slice(0, 4).join("/"); // /sites/siteKey/contents
-  let current = node;
-  while (current.getParent() && (current.getParent() as JCRNodeWrapper).getPath() !== contentsPath) {
-    current = current.getParent() as JCRNodeWrapper;
-  }
-  return current;
-}
+```sql
+AND post.[publicationDate] IS NOT NULL
+ORDER BY post.[publicationDate] DESC
 ```
 
-> ⚠️ `getParent()` returns `Node` (JCR base type), not `JCRNodeWrapper`. Always cast: `current.getParent() as JCRNodeWrapper`.
+### Nested content folders
 
-### Recursively render a folder tree
+Use `ISDESCENDANTNODE` to cover nested folder trees automatically. Switch to `ISCHILDNODE` only when you intentionally want one level.
 
-Use a plain function (not a React component) for recursive tree rendering — avoids hook scope issues:
+---
 
-```tsx
-import type { ReactElement } from "react";
-import { buildNodeUrl } from "@jahia/javascript-modules-library";
-import type { JCRNodeWrapper } from "org.jahia.services.content";
-
-function renderTree(
-  folder: JCRNodeWrapper,
-  contentNodeType: string,
-  depth: number = 0,
-): ReactElement | null {
-  const items: Array<{ type: "folder" | "item"; node: JCRNodeWrapper }> = [];
-  const iter = folder.getNodes();
-  while (iter.hasNext()) {
-    const node = iter.nextNode() as JCRNodeWrapper;
-    if (node.isNodeType("jnt:contentFolder")) items.push({ type: "folder", node });
-    else if (node.isNodeType(contentNodeType)) items.push({ type: "item", node });
-  }
-  if (items.length === 0) return null;
-
-  return (
-    <ul>
-      {items.map(({ type, node }) => {
-        const key = node.getPath();
-        if (type === "folder") {
-          return (
-            <li key={key}>
-              <strong>{node.getPropertyAsString("jcr:title") || node.getName()}</strong>
-              {renderTree(node, contentNodeType, depth + 1)}
-            </li>
-          );
-        }
-        return (
-          <li key={key}>
-            <a href={buildNodeUrl(node)}>
-              {node.getPropertyAsString("jcr:title") || node.getName()}
-            </a>
-          </li>
-        );
-      })}
-    </ul>
-  );
-}
-```
+## Query checklist
 
-Use `folder.getNodes()` (returns a `NodeIterator`) — call `.hasNext()` / `.nextNode()` to iterate. The iterator preserves orderable-folder order (creation/manual reordering in jContent), which `ORDER BY jcr:name` would not.
+- [ ] Query is constrained to `/sites/<siteKey>/contents/...` or another specific subtree
+- [ ] Node type is specific, not overly broad
+- [ ] Sort order matches the UX need
+- [ ] Draft or publish filtering is explicit
+- [ ] Detail-page types use `jmix:mainResource` only when needed
+- [ ] The query has been validated against `/jahia-jcr-sql2` guardrails
 
 ---
 
-- **JCR repository browser**: http://localhost:8080/modules/tools/jcrBrowser.jsp
-- **Installed definitions browser**: http://localhost:8080/modules/tools/definitionsBrowser.jsp
-
----
+## Related skills
 
-## Validation checklist
-- [ ] Content folder exists in Jahia UI under `contents/`
-- [ ] Site key in query matches the actual site key (use `renderContext.getSite().getName()` in code)
-- [ ] Query returns expected results in the built-in query component
-- [ ] `jmix:mainResource` added if items need a full-page view
-- [ ] Draft/publish filtering works correctly
-- [ ] `buildNodeUrl(currentNode)` used for item links
+- `/jahia-jcr-sql2` — SQL2 syntax, full-text, joins, pagination, and performance
+- `/jahia-dev-build-component` — build the listing component that renders query results
+- `/jahia-dev-define-content-type` — create the queried content type and folder types
 
-## Troubleshooting
-> https://academy.jahia.com/tutorials-get-started/front-end-developer/making-a-blog

package/dist/windsurf/.windsurf/skills/jahia-dev-review-cnd/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: jahia-dev-review-cnd
+description: Use after writing any CND file to validate it against Jahia best practices. Runs the deterministic cnd-checker script and reports PASS / FAIL with file:line citations and fixes. Run /jahia-dev-review-cnd <path> to check a specific file or directory, or without arguments to check all CND files in the current module.
+allowed-tools: Bash
+---
+
+## Step 1 — Run the checker
+
+```bash
+CND_SCRIPT=$(find .claude .agents -name "check-cnd.mjs" 2>/dev/null | head -1)
+node "$CND_SCRIPT" <path-to-file-or-directory>
+# or, to check all CND files in the module:
+node "$CND_SCRIPT" src/
+```
+
+The script exits with code 0 for PASS and code 1 for FAIL.
+
+## Step 2 — Fix and repeat until clean
+
+This is a loop. Run the checker, fix every issue reported, run it again. Repeat until the result is `PASS`.
+
+- **FAIL** — fix every issue, re-run. Do not proceed until exit code is 0.
+- **PASS** — clean. Continue.
+
+---
+
+## Antipattern reference
+
+The checker enforces these patterns. Use this as a guide when interpreting output or fixing issues manually.
+
+### `rawStringLink`
+Property whose name contains `link`, `url`, `href`, or `path` declared as `(string)`.
+**Fix**: Use the link picker:
+```cnd
+- j:linkType (string, choicelist[linkTypeInitializer]) mandatory
+```
+
+### `singleHardcodedCta`
+A type with both a CTA label (`ctaText`, `ctaLabel`, `buttonText`, `buttonLabel`) and a CTA link (`ctaLink`, `ctaUrl`, `ctaHref`, `buttonLink`) as flat properties, with no child node.
+**Fix**: Replace with a child node:
+```cnd
++ * (ns:cta)
+
+[ns:cta] > jnt:content, nsmix:component
+ - label (string) i18n mandatory
+ - j:linkType (string, choicelist[linkTypeInitializer]) mandatory
+```
+
+### `directDroppable`
+A concrete type extending `jmix:droppableContent` directly.
+**Fix**: Extend the module mixin: `[ns:hero] > jnt:content, nsmix:component`
+
+### `missingRatingConstraint`
+`rating (long)` without a range constraint — unconstrained ratings cause data integrity issues.
+**Fix**: Add `< "[1,5]"`
+
+### `redundantImageAlt`
+`imageAlt (string)` alongside an image weakreference. The image node already has `jcr:title`.
+**Fix**: Remove `imageAlt`. In the view: `image.getPropertyAsString("jcr:title") ?? ""`
+
+### `rawTitleProp`
+Property named `title`, `heroTitle`, `pageTitle`, or `sectionTitle` typed as `(string)`.
+**Fix**: Remove it, extend `mix:title`. Access as `props["jcr:title"]`.
+
+### `weakrefNoConstraint`
+`(weakreference)` with no `< ` type constraint.
+**Fix**: Add constraint — `< jmix:image` for images, `< jnt:file` for files.
+
+### `weakrefWrongConstraint`
+`< 'jnt:file'` (quoted form).
+**Fix**: `< jmix:image` (unquoted).
+
+### `missingI18n`
+User-visible string (`title`, `text`, `label`, `description`, `subtitle`, `caption`, `alt`, `heading`, `summary`, `excerpt`, `body`) without `i18n`.
+**Fix**: Add `i18n` after the type declaration.
+
+### `studioOnly`
+Any use of `jmix:studioOnly`.
+**Fix**: Replace with `jmix:hiddenType`.

package/dist/windsurf/.windsurf/skills/jahia-dev-review-cnd/scripts/check-cnd.d.mts

@@ -0,0 +1,13 @@
+export interface CndIssue {
+  file: string;
+  line?: number;
+  pattern: string;
+  message: string;
+  fix: string;
+}
+
+export function checkCndFiles(projectDir: string): {
+  score: number;
+  issues: CndIssue[];
+  filesChecked: number;
+};