npm - @jahia/agentic - Versions diffs - 0.4.0 → 0.5.0 - Mend

@jahia/agentic 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (451) hide show

package/dist/kiro/.kiro/skills/jahia-dev-create-page-template/SKILL.md ADDED Viewed

@@ -0,0 +1,341 @@
+---
+name: jahia-dev-create-page-template
+description: Creates a Jahia page template with Areas and AbsoluteAreas. Use when asked to add a new page layout, create a page template, or set up a shared area like a header or footer.
+allowed-tools: Bash, Read, Write, Edit
+---
+## Overview
+A **page template** defines the full layout of a page. It is registered with `componentType: "template"` and always targets `jnt:page`. Templates contain **Areas** (per-page content) and **AbsoluteAreas** (shared across all pages, e.g. footer, navbar).
+---
+> ⚠️ **CMS rule — never hardcode links in templates.** Navigation links, logo hrefs, footer links — all must come from contributed content (via props, `buildNodeUrl`, or `j:linkType`). Do not put literal URLs in template code.
+## Step 1 — Create the template file
+Page templates live in `src/templates/<ModuleName>Template/`. Name the file `default.server.tsx`.
+```tsx
+import React from "react";
+import { Area, AbsoluteArea, getChildNodes, buildNodeUrl, jahiaComponent } from "@jahia/javascript-modules-library";
+import styles from "./template.module.css";
+jahiaComponent(
+  {
+    componentType: "template",   // "template" for full pages, not "view"
+    nodeType: "jnt:page",        // always jnt:page for page templates
+    displayName: "Default Template",
+    name: "default",
+  },
+  ({ "jcr:title": title }, { renderContext, mainNode }) => {
+    // Pages live under /sites/<key>/home — not directly under the site node
+    const siteHome = renderContext.getSite().getNode("home");
+    const navPages = getChildNodes(siteHome, -1, 0, n => n.isNodeType("jnt:page"));
+    const siteName = renderContext.getSite().getPropertyAsString("j:siteTitle") ?? renderContext.getSite().getName();
+    return (
+      <html lang="en">
+        <head>
+          <meta charSet="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1" />
+          {/* jcr:title is the short page name — template appends site name for SEO */}
+          <title>{title}{siteName ? ` | ${siteName}` : ""}</title>
+        </head>
+        <body>
+          <a href="#main-content" className={styles.skipLink}>Skip to main content</a>
+          <header className={styles.header}>
+            <nav aria-label="Main navigation">
+              <ul className={styles.navList}>
+                <li key={siteHome.getPath()}>
+                  <a href={buildNodeUrl(siteHome)} aria-current={siteHome.getPath() === mainNode.getPath() ? "page" : undefined}>
+                    {siteHome.getPropertyAsString("jcr:title") ?? siteHome.getName()}
+                  </a>
+                </li>
+                {navPages.map(page => (
+                  <li key={page.getPath()}>
+                    <a
+                      href={buildNodeUrl(page)}
+                      aria-current={page.getPath() === mainNode.getPath() ? "page" : undefined}
+                    >
+                      {page.getPropertyAsString("jcr:title") ?? page.getName()}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </nav>
+          </header>
+          <main id="main-content">
+            <h1 className={styles.pageTitle}>{title}</h1>
+            <Area name="pagecontent" />
+          </main>
+          <footer className={styles.footer}>
+            <AbsoluteArea name="footer" parent={renderContext.getSite()} />
+            <p className={styles.copyright}>{"© "}{renderContext.getSite().getName()}</p>
+          </footer>
+        </body>
+      </html>
+    );
+  },
+);
+```
+---
+## Step 2 — Choose: Area vs AbsoluteArea
+| | `<Area>` | `<AbsoluteArea>` |
+|---|---|---|
+| Content | Per-page (each page has its own) | Shared across all pages |
+| Use for | Page body, hero, sections | Footer, navbar, sidebar |
+| `parent` prop | Not needed | Set to `renderContext.getSite()` for site-wide |
+---
+## Step 3 — Use typed area nodes (required for good editorial UX)
+Instead of a single generic area type, define **one area type per section** with a tight child constraint. This ensures editors only see relevant content types in each area's "New content" menu.
+```cnd
+// settings/definitions.cnd
+[namespacemix:pageComponent] > namespacemix:component mixin
+// ✅ Typed areas — editors only see the right types per area
+// Use jmix:hiddenType (NOT jmix:studioOnly) — hides from picker while keeping rendering intact
+[namespace:heroArea] > jnt:content, jmix:list, jmix:hiddenType orderable
+ + * (namespace:heroSection)
+[namespace:featuresArea] > jnt:content, jmix:list, jmix:hiddenType orderable
+ + * (namespace:featureCard)
+// Generic fallback — use only when no tighter constraint makes sense
+[namespace:pageArea] > jnt:content, jmix:list, jmix:hiddenType orderable
+ + * (namespacemix:pageComponent)
+```
+Then in the template:
+```tsx
+<Area name="hero"     nodeType="namespace:heroArea" />
+<Area name="features" nodeType="namespace:featuresArea" />
+<Area name="footer"   nodeType="namespace:pageArea" />   // generic ok for footer
+```
+> ⚠️ **Never use a generic `pageArea` for every area.** If all areas accept all `pageComponent` types, editors will see "New Hero Section" as an option in a feature card area, which is confusing and error-prone.
+> **Sections driven by content folders** (e.g. a tutorials listing that queries `/contents/tutorials/`) should NOT use an Area at all — the template renders them via a server-side query component. Exposing an Area there invites editors to manually add duplicates of auto-queried content.
+> ⚠️ **CSS gotcha — `Area` renders children directly, no wrapper div.** When wrapping an `<Area>` in a container div and styling children with `.container > div { display: grid }`, the grid won't apply because there is no intermediate `div` — the area's child components are rendered as direct children of `.container`. Always apply grid/flex layout **on the container itself** when its only content is an Area:
+> ```css
+> /* ✅ correct — grid on the container that wraps the Area */
+> .featuresSection .container { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 1.5rem; }
+> /* ❌ wrong — no div is inserted between container and the card articles */
+> .container > div { display: grid; }
+> ```
+### ⚠️ After defining `pageComponent` — update existing components
+**This is the most common mistake:** if the module already has content types, they all extend `namespacemix:component`. After introducing the custom area type, **editors will not be able to drop anything** until you update the page-level components to extend `namespacemix:pageComponent` instead.
+Scan all `definition.cnd` files and update every component that should be droppable in page areas:
+```cnd
+// Before (editors can't drop in pageArea):
+[namespace:heroSection] > jnt:content, namespacemix:component
+// After (editors can drop in pageArea):
+[namespace:heroSection] > jnt:content, namespacemix:pageComponent
+```
+**Which components need `pageComponent`?**
+- Standalone page sections (hero, feature cards, text blocks, etc.) → `namespacemix:pageComponent`
+- Child-only types (CTA inside hero, card inside list) → keep `namespacemix:component`
+- `jmix:mainResource` types stored in content folders → keep `namespacemix:component`
+---
+## Step 4 — Page template vs sectioning component
+Before creating a new page template, ask:
+| Is this… | Use a… |
+|---|---|
+| A new top-level page layout (different column structure, hero slot) | **New page template** |
+| A layout variation that could be reused as a section on any page | **Sectioning component** (use the build-component skill) |
+| A minor style difference on an existing template | **Named view** of the existing template |
+**Guideline**: keep page templates small (1–4). Use sectioning components for compositional differences.
+---
+## Step 5 — Define structural (non-selectable) container nodes
+Some nodes are purely structural — they hold child nodes but shouldn't appear in the component picker. Omit `namespacemix:component` and add `jmix:hiddenType`:
+```cnd
+[namespace:header] > jnt:content, jmix:hiddenType
+ + hero (namespace:heroSection)
+```
+Render it with `RenderChild`:
+```tsx
+// src/components/Header/default.server.tsx
+import { jahiaComponent, RenderChild } from "@jahia/javascript-modules-library";
+jahiaComponent(
+  { componentType: "view", nodeType: "namespace:header" },
+  () => <RenderChild name="hero" />,
+);
+```
+---
+## Step 6 — Bootstrap site structure with import.xml
+`import.xml` provisions every new site created from this template set. **Always update it** — editors cannot contribute if there's no page structure to start from.
+**Minimum required:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<content xmlns:j="http://www.jahia.org/jahia/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0">
+  <modules jcr:primaryType="jnt:modules">
+    <your-module-name>
+      <!-- Homepage — MUST use your actual template name, not "basic" -->
+      <home j:isHomePage="true" j:templateName="homepage" jcr:primaryType="jnt:page">
+        <j:translation_en jcr:language="en" jcr:mixinTypes="mix:title"
+          jcr:primaryType="jnt:translation" jcr:title="Home"/>
+        <!-- Pre-create area nodes so editors can start dropping content immediately -->
+        <hero jcr:primaryType="namespace:pageArea"/>
+        <main jcr:primaryType="namespace:pageArea"/>
+      </home>
+      <!-- Add sub-pages for each template you created -->
+      <documentation j:templateName="documentation" jcr:primaryType="jnt:page">
+        <j:translation_en jcr:language="en" jcr:mixinTypes="mix:title"
+          jcr:primaryType="jnt:translation" jcr:title="Documentation"/>
+        <hero jcr:primaryType="namespace:pageArea"/>
+      </documentation>
+      <!-- Offline management pages — never published, system-name locked -->
+      <drafts jcr:primaryType="jnt:page" j:templateName="basic"
+        jcr:mixinTypes="jmix:systemNameReadonly jmix:nolive">
+        <j:translation_en jcr:language="en" jcr:mixinTypes="mix:title"
+          jcr:primaryType="jnt:translation" jcr:title="Drafts"/>
+      </drafts>
+      <!-- Content folders — store jmix:mainResource content here, not in pages -->
+      <contents jcr:primaryType="jnt:contentFolder">
+        <articles jcr:primaryType="jnt:contentFolder"
+          jcr:mixinTypes="jmix:contributeMode" j:contributeTypes="namespace:docArticle">
+          <j:translation_en jcr:language="en" jcr:primaryType="jnt:translation" jcr:title="Articles"/>
+        </articles>
+      </contents>
+    </your-module-name>
+  </modules>
+</content>
+```
+**Rules:**
+- `j:templateName` must match the `name:` in your `jahiaComponent` call — if it's wrong, editors get a blank page
+- Pre-create area nodes (`jcr:primaryType="namespace:pageArea"`) so editors don't face empty containers on first open
+- Add a starter component in the hero area so the page isn't visually blank (optional but strongly recommended)
+- Content folders with `jmix:contributeMode` + `j:contributeTypes` restrict what editors can create in them
+- `jmix:systemNameReadonly` prevents editors from renaming or moving management pages; `jmix:nolive` prevents accidental publishing
+---
+## Step 7 — Build and deploy
+```bash
+yarn build && yarn jahia-deploy
+```
+> ⚠️ **Do not use `yarn dev`** — it is a continuous file watcher that should only be started manually when needed for rapid iteration. For agentic workflows, always use `yarn build && yarn jahia-deploy` for explicit, one-shot deploys.
+After deploying, the new template will appear in the **template selection** step when creating a new page (right-click on a page in the sidebar → **+ New Page**).
+---
+## Common patterns
+### Single column with shared footer
+```tsx
+<Layout title={title}>
+  <Area name="main" />
+  <AbsoluteArea name="footer" parent={renderContext.getSite()} nodeType="namespace:footer" />
+</Layout>
+```
+### Two-column layout
+```tsx
+<Layout title={title}>
+  <div style={{ display: "grid", gridTemplateColumns: "1fr 2fr", gap: "2rem" }}>
+    <Area name="sidebar" />
+    <Area name="main" />
+  </div>
+</Layout>
+```
+### Edit mode-aware rendering
+```tsx
+({ "jcr:title": title }, { renderContext }) => {
+  const isEdit = renderContext.isEditMode();
+  return (
+    <Layout title={title}>
+      <Area name="main" />
+      <nav style={{ flexDirection: isEdit ? "column" : "row" }}>
+        <AbsoluteArea name="footer" parent={renderContext.getSite()} />
+      </nav>
+    </Layout>
+  );
+}
+```
+---
+## Validation checklist
+- [ ] `componentType: "template"` and `nodeType: "jnt:page"`
+- [ ] `name` is set (used in Jahia UI template picker)
+- [ ] Skip link present: `<a href="#main-content">Skip to main content</a>`
+- [ ] Nav built from `getChildNodes(site.getNode('home'), ...)` — pages are children of `home`, not of the site node
+- [ ] `<h1>{title}</h1>` in the template — no `<h1>` in any component
+- [ ] `<footer>` landmark always has visible content (never empty)
+- [ ] Areas use a custom area node type (not bare `<Area name="..."/>`)
+- [ ] Custom area type has `jmix:list`, `jmix:hiddenType`, and `orderable`
+- [ ] Decision made: page template vs sectioning component (see Step 4)
+- [ ] `yarn build && yarn jahia-deploy` run and template appears in Jahia UI
+## Troubleshooting
+### 🚨 Area renders blank — content invisible
+**Symptom:** An Area in your template produces no HTML output at all, even though you can see children in jContent.
+**Root cause:** Jahia's `Area` component auto-creates the JCR area node using its declared `nodeType` on first page load. If that node was subsequently **deleted and recreated manually** (e.g. via GraphQL) with a *different* type, the declared type and the actual JCR type no longer match — and Jahia silently renders nothing.
+**Fix:** Delete the mistyped node and let Jahia recreate it automatically:
+```graphql
+mutation {
+  jcr {
+    mutateNode(pathOrId: "/sites/mySite/home/hero") {
+      delete
+    }
+  }
+}
+```
+Visit the page — Jahia recreates the node with the correct type and children render again.
+**Prevention:** Never manually create area nodes via GraphQL with a type that differs from the `nodeType` declared in the template. Always let Jahia auto-create area nodes on first render.
+> https://academy.jahia.com/tutorials-get-started/front-end-developer/the-about-us-page

package/dist/kiro/.kiro/skills/jahia-dev-create-template-set/SKILL.md ADDED Viewed

@@ -0,0 +1,205 @@
+---
+name: jahia-dev-create-template-set
+description: Scaffolds a new Jahia JavaScript template set (React). Use this when asked to create a new Jahia module, website, or project.
+---
+## About Jahia JavaScript Modules
+This skill only covers **JavaScript Modules** — React-based template sets for Jahia 8+. This is the recommended approach for all new Jahia projects.
+### JS modules vs Java modules vs Next.js
+| | Java Modules | JS Modules | Next.js (Headless) |
+|---|---|---|---|
+| Availability | All versions | 8.2+ | Depends on setup |
+| Separate runtime | No | No | Yes |
+| GraphQL required | No | No | Yes |
+| CMS navigation/cache/auth | Yes | Yes | No |
+| Packaging | Maven/jar | NPM/tgz | NPM/tgz |
+| Templating | JSP | JSX | JSX |
+| Module descriptor | pom.xml | package.json | Separate module |
+Jahia recommends JS or Java modules for most projects. Next.js should only be chosen when integrating with an existing Next.js codebase.
+### How JS modules run: GraalVM + GraalJS
+Jahia JS modules run inside **GraalJS** (part of GraalVM) — a fully ECMAScript-2019-compliant JS engine on the JVM. GraalVM Native Image is **not** used (incompatible with OSGi). Official Jahia Docker images ship with GraalVM pre-configured.
+**Build pipeline:** Yarn 4 + Vite. The `npm init @jahia/module@latest` scaffolder generates `vite.config.mjs` handling TypeScript, CSS Modules, and client-side JS bundles.
+**tgz → OSGi transformation:** On install, Jahia converts the NPM tgz into an OSGi bundle. Key `package.json` → `MANIFEST.MF` mappings:
+| package.json field | MANIFEST.MF clause |
+|---|---|
+| `jahia.module-dependencies` | `Jahia-Depends` |
+| `jahia.server` | `Jahia-NPM-InitScript` |
+| `jahia.required-version` | `Jahia-Required-Version` |
+| `jahia.module-type` | `Jahia-Module-Type` |
+| `jahia.static-resources` | `Jahia-Static-Resources` |
+**Request flow:**
+1. Browser request → Jahia servlet
+2. `TemplateNodeFilter` resolves the template identifier
+3. `ViewsRegistrar` resolves the JS script for the template
+4. `GraalVMEngine` pulls a `ContextProvider` from its pool, renders via GraalJS
+5. `<Area>` / `<Render>` components may call `RenderService` to render child views
+6. Final HTML assembled and returned
+The engine maintains a pool of polyglot contexts (one per thread). Each context runs all init scripts (`dist/server/index.js`) on creation. A version counter invalidates stale contexts when modules are added or removed.
+---
+## Step 1 — Check prerequisites
+Before scaffolding, verify Node.js and Yarn are available:
+```bash
+node --version   # must be 22.14+
+yarn --version   # must be 4.9+
+```
+Node 22.14+ is required. Yarn is managed by **Corepack** (bundled with Node) — no global install needed:
+```bash
+corepack enable yarn
+```
+If Node is missing or outdated, install it from [nodejs.org/en/download](https://nodejs.org/en/download) — select **for your platform** and **with Yarn**. Alternatively use mise:
+```bash
+mise use node@lts && corepack enable yarn
+```
+Do not proceed until both `node --version` (22.14+) and `yarn --version` (4.9+) pass.
+---
+## Step 2 — Scaffold the module
+Run the interactive CLI and **show the user its full output**:
+```bash
+npm init @jahia/module@latest <project-name>
+```
+The CLI will prompt interactively for:
+| Prompt | Guidance |
+|--------|----------|
+| Module name | kebab-case, e.g. `my-site` |
+| Output directory | accept the default (`./<module-name>`) |
+| Module type | see below |
+**Module type — always choose a template set:**
+- `A minimal Hello World template set` ✅ — best starting point, includes working components
+- `An empty template set` — blank canvas, for experienced developers
+Once the project is created, the CLI will suggest commands to start it. Run them in order — they start Docker (Jahia) and push the module.
+---
+## Step 3 — After generation
+1. `cd <project-name>`
+2. `yarn install` — install dependencies
+To run the module locally, use the `/jahia-dev-start-local` skill next.
+---
+## Step 4 — Build and deploy the module
+Once Jahia is running at `http://localhost:8080`, build and deploy the module:
+```bash
+yarn build && yarn jahia-deploy
+```
+`yarn jahia-deploy` (from `@jahia/vite-plugin` 1.2.0+) always uses curl and defaults to `http://localhost:8080` / `root:root1234` — no `.env` configuration is required for standard local development.
+Verify the module is installed:
+```
+tool: content.get
+args: { "path": "/modules/<module-name>" }
+```
+Replace `<module-name>` with the `name` from `package.json`. The response should contain the module node.
+---
+## Step 5 — Create a new site in Jahia
+After the module is deployed, create the site via MCP:
+```
+tool: site.create
+args: {
+  "siteKey": "<module-name>",
+  "title": "My Site",
+  "templateSet": "<module-name>",
+  "defaultLanguage": "en",
+  "serverName": "localhost"
+}
+```
+Replace `<module-name>` with the `name` from `package.json`. `templateSet` must exactly match the deployed module name.
+Verify the site was created:
+```
+tool: site.list
+```
+The site key must appear in the response. If it does not, check that `templateSet` exactly matches the deployed module name.
+---
+## Generated structure (Hello World template set)
+```
+<module-name>/
+├── .github/               # GitHub Actions (builds on push)
+├── .vscode/               # VSCode config — install recommended extensions!
+├── src/
+│   ├── components/        # React content type components
+│   └── templates/         # Page layouts
+├── settings/
+│   ├── content-types-icons/   # 32×32 PNG icons per content type
+│   ├── definitions.cnd        # Module-level CND (mixins, base types)
+│   ├── import.xml             # Content/pages provisioned on site creation
+│   ├── locales/               # i18n (en.json, fr.json, ...)
+│   ├── resources/             # Editor UI labels (.properties files)
+│   └── template-thumbnail.png # Shown in the Jahia template picker
+├── static/                # Static files (images, fonts, vendor CSS/JS)
+├── docker-compose.yml     # Local Jahia instance
+├── docker/provisioning.yml
+├── .env                   # Environment variables for build tools
+├── .node-version          # Node version pin (used by GitHub Actions)
+├── package.json
+├── vite.config.mjs
+└── tsconfig.json
+```
+`static/` is served at `/modules/<name>/` — reference files there with `buildModuleFileUrl("image.png")`.
+---
+## References
+- https://github.com/Jahia/javascript-modules (monorepo — includes the `create-module` archetype)
+## Troubleshooting
+If anything goes wrong during setup or scaffolding, refer to the official Jahia front-end developer setup guide:
+> https://academy.jahia.com/tutorials-get-started/front-end-developer/setting-up-your-dev-environment
+---
+## Validation checklist
+- [ ] `node --version` reports 22.14+
+- [ ] `yarn --version` reports 4.9+ (via Corepack)
+- [ ] Module directory created with expected structure
+- [ ] `yarn install` completes without errors
+- [ ] `yarn build && yarn jahia-deploy` succeeds — module appears at `/modules/<name>` in JCR
+- [ ] Site created with `site.create` — `site.list` confirms site key exists