@jahia/agentic 0.4.1 → 0.5.1

package/dist/kiro/.kiro/skills/jahia-dev-review-cnd/scripts/check-cnd.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+function findCndFiles(dir) {
+  const results = [];
+  function walk(current) {
+    try {
+      const stat = statSync(current);
+      if (stat.isFile()) {
+        if (current.endsWith(".cnd")) results.push(current);
+        return;
+      }
+      for (const entry of readdirSync(current, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== ".git") {
+          walk(join(current, entry.name));
+        } else if (entry.isFile() && entry.name.endsWith(".cnd")) {
+          results.push(join(current, entry.name));
+        }
+      }
+    } catch {
+      // skip unreadable paths
+    }
+  }
+  walk(dir);
+  return results;
+}
+
+function checkFile(filePath, content) {
+  const issues = [];
+  const lines = content.split("\n");
+
+  lines.forEach((line, i) => {
+    const lineNum = i + 1;
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//") || trimmed.startsWith("<")) return;
+
+    // rawStringLink
+    if (
+      /^-\s+\w*(Url|Href|Link)\s+\(string[,)]/i.test(trimmed) &&
+      !/choicelist\[linkTypeInitializer\]/.test(trimmed)
+    ) {
+      const propName = trimmed.match(/^-\s+(\w+)/)?.[1] ?? "unknown";
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "rawStringLink",
+        message: `"${propName}" uses (string) for a link/url — use choicelist[linkTypeInitializer]`,
+        fix: "Replace with: - j:linkType (string, choicelist[linkTypeInitializer]) mandatory",
+      });
+    }
+
+    // rawTitleProp
+    if (/^-\s+(title|heroTitle|pageTitle|sectionTitle)\s+\(string[,)]/i.test(trimmed)) {
+      const propName = trimmed.match(/^-\s+(\w+)/)?.[1] ?? "unknown";
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "rawTitleProp",
+        message: `"${propName}" is a plain string — extend mix:title instead`,
+        fix: "Add mix:title to the type declaration and remove this property",
+      });
+    }
+
+    // weakrefNoConstraint: (weakreference) with no < constraint on same line
+    if (/\(weakreference[,)]/.test(trimmed) && !/<\s*\S/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "weakrefNoConstraint",
+        message: "Unconstrained weakreference — add a type constraint",
+        fix: "Add e.g. (weakreference, picker[type='image']) < jmix:image",
+      });
+    }
+
+    // weakrefWrongConstraint
+    if (/< ['"]jnt:file['"]/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "weakrefWrongConstraint",
+        message: "< 'jnt:file' (quoted) does not enforce image type",
+        fix: "Replace with < jmix:image for images",
+      });
+    }
+
+    // missingI18n: user-visible string without i18n
+    if (
+      /^-\s+\w+\s+\(string(,\s*(textarea|richtext))?[,)]/.test(trimmed) &&
+      !/ i18n/.test(trimmed) &&
+      !/^-\s+j:/.test(trimmed) &&
+      /(title|text|label|description|subtitle|caption|alt|heading|summary|excerpt|body)/i.test(trimmed)
+    ) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "missingI18n",
+        message: "User-visible string property missing i18n",
+        fix: "Add i18n keyword after the type declaration",
+      });
+    }
+
+    // directDroppable: concrete type (not mixin) extending jmix:droppableContent
+    if (trimmed.startsWith("[") && /jmix:droppableContent/.test(trimmed) && !/\bmixin\b/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "directDroppable",
+        message: "Extends jmix:droppableContent directly — always extend the module component mixin",
+        fix: "Replace jmix:droppableContent with nsmix:component (or your module's equivalent)",
+      });
+    }
+
+    // studioOnly
+    if (/jmix:studioOnly/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "studioOnly",
+        message: "jmix:studioOnly causes silent rendering issues",
+        fix: "Replace with jmix:hiddenType",
+      });
+    }
+
+    // redundantImageAlt: imageAlt as plain string — image node already has jcr:title
+    if (/^-\s+imageAlt\s+\(string[,)]/i.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "redundantImageAlt",
+        message: '"imageAlt" is redundant — the image node\'s jcr:title (mix:title) serves as alt text',
+        fix: 'Remove imageAlt. In the view, use image.getPropertyAsString("jcr:title") for alt text',
+      });
+    }
+
+    // missingRatingConstraint: rating (long) without a range constraint
+    if (/^-\s+rating\s+\(long[,)]/i.test(trimmed) && !/<\s*"?\[/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "missingRatingConstraint",
+        message: '"rating" (long) has no range constraint — unconstrained ratings cause data integrity issues',
+        fix: 'Add: < "[1,5]"',
+      });
+    }
+  });
+
+  // singleHardcodedCta: check whole-file type blocks
+  const typeBlocks = content.split(/(?=^\[)/m);
+  for (const block of typeBlocks) {
+    if (!block.trim().startsWith("[")) continue;
+    const hasCtaLabel = /^\s*-\s+cta(Text|Label|ButtonText|ButtonLabel)\s+\(/im.test(block);
+    const hasCtaLink = /^\s*-\s+cta(Link|Url|Href|ButtonLink|ButtonUrl)\s+\(/im.test(block);
+    const hasChildNodes = /^\s*\+\s+/.test(block);
+    if (hasCtaLabel && hasCtaLink && !hasChildNodes) {
+      const typeName = block.match(/^\[(\S+)\]/m)?.[1] ?? "unknown";
+      const typeLineIdx = lines.findIndex((l) => l.includes(`[${typeName}]`));
+      issues.push({
+        file: filePath,
+        ...(typeLineIdx >= 0 ? { line: typeLineIdx + 1 } : {}),
+        pattern: "singleHardcodedCta",
+        message: `${typeName}: flat ctaText+ctaLink forces a single CTA — model as child nodes`,
+        fix: "Remove ctaText and ctaLink. Add: + * (ns:cta). Create a [ns:cta] type with label + j:linkType",
+      });
+    }
+  }
+
+  return issues;
+}
+
+export function checkCndFiles(projectDir) {
+  const files = findCndFiles(projectDir);
+  const allIssues = [];
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(file, "utf-8");
+      allIssues.push(...checkFile(file, content));
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  return { score: Math.exp(-allIssues.length * 0.5), issues: allIssues, filesChecked: files.length };
+}
+
+if (import.meta.main) {
+  const targetPath = resolve(process.argv[2] ?? ".");
+  const { score, issues, filesChecked } = checkCndFiles(targetPath);
+
+  console.log(`\nCND Review: ${filesChecked} file${filesChecked !== 1 ? "s" : ""} checked\n`);
+
+  if (issues.length > 0) {
+    console.log(`ISSUES (${issues.length}):`);
+    for (const issue of issues) {
+      const loc = issue.line ? `${issue.file}:${issue.line}` : issue.file;
+      console.log(`  [${issue.pattern}] ${loc}`);
+      console.log(`    ${issue.message}`);
+      console.log(`    Fix: ${issue.fix}`);
+    }
+    console.log();
+  }
+
+  const verdict = issues.length > 0 ? "FAIL" : "PASS";
+  console.log(`Result: ${verdict} (score=${score.toFixed(2)})`);
+  process.exit(issues.length > 0 ? 1 : 0);
+}

package/dist/kiro/.kiro/skills/jahia-dev-screenshot/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: jahia-dev-screenshot
+description: Takes screenshots of a reference URL and the local Jahia render for visual comparison. Use before building a view (inspiration) and after (validation).
+---
+
+# Skill: jahia-dev-screenshot
+
+Takes screenshots for two purposes:
+1. **Reference** — capture an existing site as a visual spec before building
+2. **Result** — capture the local Jahia render after building to compare
+
+---
+
+## Step 1 — Detect screenshot tool
+
+Check what is available:
+
+```bash
+# Playwright (preferred)
+npx playwright --version 2>/dev/null
+
+# Puppeteer
+node -e "require('puppeteer'); console.log('ok')" 2>/dev/null
+
+# System Chrome/Chromium
+which google-chrome || which chromium || which chromium-browser 2>/dev/null
+```
+
+Use the first one that works. If none is available, ask the user:
+
+> No screenshot tool found. Which would you like to install?
+> - `npm install -g playwright` then `npx playwright install chromium`
+> - `npm install puppeteer` (downloads Chromium automatically)
+> - I'll take the screenshots manually and paste them in
+
+If the user chooses manual, skip to Step 4 and ask them to paste the screenshots.
+
+---
+
+## Step 2 — Take reference screenshot
+
+Ask the user for the reference URL if not already provided.
+
+Create the output directory:
+```bash
+mkdir -p /tmp/jahia-screenshots
+```
+
+### With Playwright:
+```bash
+npx playwright screenshot \
+  --browser chromium \
+  --full-page \
+  "<REFERENCE_URL>" \
+  /tmp/jahia-screenshots/reference.png
+```
+
+### With Puppeteer (Node.js one-liner):
+```bash
+node -e "
+const puppeteer = require('puppeteer');
+(async () => {
+  const browser = await puppeteer.launch({ args: ['--no-sandbox'] });
+  const page = await browser.newPage();
+  await page.setViewport({ width: 1440, height: 900 });
+  await page.goto('<REFERENCE_URL>', { waitUntil: 'networkidle2' });
+  await page.screenshot({ path: '/tmp/jahia-screenshots/reference.png', fullPage: true });
+  await browser.close();
+})();
+"
+```
+
+After capturing, **view the screenshot** to use it as visual context:
+
+```
+view /tmp/jahia-screenshots/reference.png
+```
+
+Describe the key design elements you observe:
+- Layout structure (hero, grid, sidebar, etc.)
+- Color palette (dominant, accent, background)
+- Typography (heading sizes, font weight)
+- Component anatomy (what sub-elements make it up)
+
+Share this description with the user before proceeding to build.
+
+---
+
+## Step 3 — Take result screenshot (after building)
+
+Once the view is built and deployed (`yarn build` + `yarn jahia-deploy`), capture the Jahia render.
+
+Ask the user for the Jahia page URL, or construct it:
+- Default: `http://localhost:8080/cms/render/default/en/sites/<siteName>/home.html`
+- Or ask: "What is the URL of the page where the component is placed?"
+
+Jahia requires authentication. Use the `--auth` header or log in first:
+
+### With Playwright:
+```bash
+npx playwright screenshot \
+  --browser chromium \
+  --full-page \
+  "http://localhost:8080/cms/render/default/en/sites/<siteName>/home.html" \
+  /tmp/jahia-screenshots/result.png
+```
+
+> Note: if the page requires login, authenticate first:
+> ```bash
+> node -e "
+> const puppeteer = require('puppeteer');
+> (async () => {
+>   const browser = await puppeteer.launch({ args: ['--no-sandbox'] });
+>   const page = await browser.newPage();
+>   await page.setViewport({ width: 1440, height: 900 });
+>   await page.goto('http://localhost:8080/cms/login', { waitUntil: 'networkidle2' });
+>   await page.type('#username', 'root');
+>   await page.type('#password', 'root1234');
+>   await Promise.all([page.waitForNavigation(), page.keyboard.press('Enter')]);
+>   await page.goto('<PAGE_URL>', { waitUntil: 'networkidle2' });
+>   await page.screenshot({ path: '/tmp/jahia-screenshots/result.png', fullPage: true });
+>   await browser.close();
+> })();
+> "
+> ```
+
+After capturing, **view the screenshot**:
+
+```
+view /tmp/jahia-screenshots/result.png
+```
+
+---
+
+## Step 4 — Compare and report gaps
+
+View both screenshots and compare them side by side (or sequentially).
+
+Report gaps to the user:
+
+```
+## Visual Comparison
+
+### Reference: <URL>
+[description of reference]
+
+### Result: http://localhost:8080/...
+[description of result]
+
+### Gaps
+- [ ] Background color differs (reference: dark navy, result: white)
+- [ ] Hero text not centered
+- [ ] CTA button missing border-radius
+- [ ] Font size smaller than reference
+
+### Suggested fixes
+...
+```
+
+Ask: **"Would you like me to fix these gaps?"**
+
+If yes, update the view's `.tsx` and `.module.css` files using `/jahia-dev-create-view` guidance, rebuild, and re-screenshot to verify.
+
+---
+
+## Integration points
+
+This skill is called from:
+- `/jahia-dev-build-component` — Step 0 (optional reference) and Step 4 (result check)
+- `/jahia-dev-create-view` — Step 0 (optional reference) and after deploy
+
+---
+
+## References
+
+- Playwright CLI: https://playwright.dev/docs/cli
+- Puppeteer: https://pptr.dev

package/dist/kiro/.kiro/skills/jahia-dev-start-local/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: jahia-dev-start-local
+description: Starts a local Jahia instance for development and guides the user through creating their first site. Use this after creating a template set to get a running Jahia environment.
+---
+
+## Overview
+
+This skill starts a local Jahia instance for development. Two approaches are available depending on the environment. Try Docker first; fall back to bare metal only if Docker is not an option.
+
+---
+
+## Step 1 — Try Docker first (recommended)
+
+Check if Docker is available:
+
+```bash
+docker info
+```
+
+- If the command **succeeds** → proceed with Docker (Step 2)
+- If the command **fails with a connection error** → Docker Desktop is likely not running. Tell the user: **"Please start Docker Desktop and try again."** Then retry `docker info`.
+- If Docker is **not installed** → skip to Step 3 (bare metal fallback)
+
+---
+
+## Step 2 — Start with Docker Compose
+
+From the module directory (where `docker-compose.yml` lives):
+
+```bash
+docker compose up --wait
+```
+
+This will:
+- Pull and start a local Jahia instance
+- Wait until Jahia is fully ready before returning
+
+Once up, Jahia will be available at **http://localhost:8080**.
+
+**Tell the user the URL and credentials** (default: `root` / `root1234` — can only be changed in `docker-compose.yml`).
+
+Then ask the user to run the following command **themselves in a separate terminal** — do NOT run it on their behalf, as it produces continuous feedback they need to see:
+
+```
+👉 In a new terminal, from the module directory, run:
+
+    yarn dev
+
+This watches for file changes and pushes the compiled template set to the running Jahia instance. Leave it running while you develop.
+```
+
+> **Agent note:** `yarn dev` is for interactive human development only. When building features programmatically, always use `yarn build && yarn jahia-deploy` for explicit one-shot deploys — never start `yarn dev` from an agent.
+
+After `docker compose up --wait`, deploy the module immediately:
+
+```bash
+yarn build && yarn jahia-deploy
+```
+
+`yarn jahia-deploy` (from `@jahia/vite-plugin` 1.2.0+) always uses curl to `http://localhost:8080` with credentials `root:root1234` — no `.env` changes needed for standard local development.
+
+---
+
+## Step 3 — Bare metal fallback (no Docker)
+
+If Docker is not available, Jahia can be run locally with a JVM.
+
+Fetch the latest download and setup instructions from:
+
+> https://academy.jahia.com/downloads
+
+Key requirements:
+- A working JVM (Java 11 or 17)
+- The Jahia distribution ZIP or installer from the downloads page
+
+Follow the instructions on that page for the user's platform, then return here to deploy with `yarn build && yarn jahia-deploy` once Jahia is started.
+
+---
+
+## Step 4 — Create a new site in Jahia
+
+Once the module is deployed to Jahia, 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 exists:
+
+```
+tool: site.list
+```
+
+The site key must appear in the response. If it does not, check that `templateSet` exactly matches the deployed module name.
+
+Then open **Page Builder** at http://localhost:8080/jahia/page-builder to start building.
+
+---
+
+## Validation checklist
+- [ ] `docker info` succeeds (or bare metal Jahia is running)
+- [ ] `docker compose up --wait` completes without errors (Docker path)
+- [ ] Jahia UI is reachable at http://localhost:8080
+- [ ] Module deployed to Jahia (`yarn build && yarn jahia-deploy` run; or `yarn dev` in user terminal for interactive development)
+- [ ] Site created via `site.create` MCP tool with correct `templateSet`
+- [ ] `site.list` confirms site key exists
+
+## Troubleshooting
+
+If anything goes wrong during setup or startup, 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