@jahia/agentic 0.4.0 → 0.5.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-site-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: jahia-dev-site-review
+description: Scores live pages for accessibility (WCAG 2.1 AA via axe-core) and SEO (title, meta description, h1, alt). Use after deploying to get a pass/fail signal with per-violation detail before completing development.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# Skill: jahia-dev-site-review
+
+Runs automated a11y and SEO checks against every URL in `pages.json`. Reports a numeric score per page, lists violations by severity, and exits non-zero on any critical/serious a11y violation or missing SEO baseline.
+
+**A11y scoring:** `Math.exp(-Σ impact_weights)` where `critical=1, serious=0.5, moderate=0.25, minor=0.1`. Score of 1.0 = perfect; 0.607 = one serious violation.
+
+---
+
+## Step 1 — Ensure tooling is installed
+
+```bash
+node -e "require('@axe-core/playwright'); require('playwright')" 2>/dev/null || \
+  npm install --no-save @axe-core/playwright playwright && npx playwright install chromium --with-deps
+```
+
+---
+
+## Step 2 — Run the review
+
+```bash
+SCRIPT=$(find .claude .agents -name "review-pages.mjs" 2>/dev/null | head -1)
+node "$SCRIPT" 2>&1 | tee /tmp/site-review.txt
+```
+
+---
+
+## Step 3 — Interpret and fix
+
+The script exits 1 if any page has:
+- A `🔴 [critical]` or `🔴 [serious]` a11y violation
+- A `🔍 SEO` issue (missing title, meta description, h1, or img alt)
+
+`🟡 [moderate]` and `🟡 [minor]` violations are reported but do not fail the run — fix them for a higher score.
+
+**Common violations and where to fix them:**
+
+| Violation | Fix location |
+|---|---|
+| `landmark-*` empty nav or footer | Page template — ensure `<nav>` has inline content, `<footer>` has fallback text |
+| `page-has-heading-one` | Page template — add `<h1>{title}</h1>` |
+| `image-alt` | Component `.server.tsx` — use `imageAlt \|\| title \|\| 'Image'` |
+| `color-contrast` | Component `.module.css` — check foreground/background ratio ≥ 4.5:1 |
+| `heading-order` | Component — components start at `<h2>`, sub-items at `<h3>` |
+| Missing `<title>` | Page template `<head>` |
+| Missing meta description | Page template `<head>` — add `<meta name="description" content={…} />` |
+| Multiple `<h1>` | Remove `<h1>` from components; only the template renders one |
+
+After fixing, redeploy and re-run:
+
+```bash
+yarn build && yarn jahia-deploy
+node "$SCRIPT"
+```
+
+Iterate until the script exits 0.
+
+---
+
+## Validation checklist
+- [ ] Script exits 0 (no critical/serious violations, no SEO issues)
+- [ ] Average a11y score ≥ 0.8
+- [ ] Every page has a unique, non-empty `<title>`
+- [ ] Every page has `<meta name="description">`
+- [ ] Every page has exactly one `<h1>`

package/dist/kiro/.kiro/skills/jahia-dev-site-review/scripts/review-pages.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Runs a11y (axe-core) + SEO checks on every URL in pages.json.
+// Exits 1 if any page has critical/serious a11y violations or missing SEO basics.
+import { chromium } from "playwright";
+import { AxeBuilder } from "@axe-core/playwright";
+import { readFileSync } from "fs";
+
+const IMPACTS = { minor: 0.1, moderate: 0.25, serious: 0.5, critical: 1 };
+
+const urls = JSON.parse(readFileSync("pages.json", "utf-8"));
+const browser = await chromium.launch({ args: ["--no-sandbox"] });
+const context = await browser.newContext();
+const page = await context.newPage();
+
+const results = [];
+
+for (const url of urls) {
+  process.stdout.write(`\nChecking ${url} … `);
+  await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
+
+  // A11y
+  const axe = await new AxeBuilder({ page })
+    .withTags(["wcag2a", "wcag2aa", "wcag21aa"])
+    .analyze();
+
+  const a11yScore = Math.exp(
+    -axe.violations.reduce((t, v) => t + (IMPACTS[v.impact] ?? 0), 0),
+  );
+
+  // SEO
+  const title = await page.title();
+  const metaDesc = await page
+    .$eval('meta[name="description"]', el => el.getAttribute("content"))
+    .catch(() => null);
+  const h1s = await page.$$eval("h1", els => els.map(e => e.textContent?.trim()));
+  const imgsMissingAlt = await page.$$eval(
+    "img",
+    els => els.filter(e => !e.getAttribute("alt")).map(e => e.outerHTML.slice(0, 80)),
+  );
+
+  const seoIssues = [];
+  if (!title) seoIssues.push("missing <title>");
+  if (!metaDesc) seoIssues.push("missing <meta name=description>");
+  if (h1s.length === 0) seoIssues.push("no <h1>");
+  if (h1s.length > 1) seoIssues.push(`${h1s.length} <h1> elements (must be exactly 1)`);
+  if (imgsMissingAlt.length > 0)
+    seoIssues.push(`${imgsMissingAlt.length} <img> missing alt attribute`);
+
+  process.stdout.write(`a11y=${a11yScore.toFixed(3)}\n`);
+  results.push({ url, a11yScore, violations: axe.violations, seoIssues });
+}
+
+await browser.close();
+
+// ── Report ──────────────────────────────────────────────────────────────────
+let failed = false;
+
+for (const r of results) {
+  const critical = r.violations.filter(v => v.impact === "critical" || v.impact === "serious");
+  const pageOk = critical.length === 0 && r.seoIssues.length === 0;
+  if (!pageOk) failed = true;
+
+  console.log(`\n${"─".repeat(70)}`);
+  console.log(`${pageOk ? "✅" : "❌"} ${r.url}`);
+  console.log(`   A11y score : ${r.a11yScore.toFixed(3)}  (1.0 = perfect)`);
+
+  for (const v of r.violations) {
+    const marker = v.impact === "critical" || v.impact === "serious" ? "🔴" : "🟡";
+    console.log(`   ${marker} [${v.impact}] ${v.id} — ${v.description} (${v.nodes.length} node${v.nodes.length !== 1 ? "s" : ""})`);
+    for (const node of v.nodes.slice(0, 3)) {
+      console.log(`        ${node.html.slice(0, 100)}`);
+    }
+  }
+
+  for (const issue of r.seoIssues) {
+    console.log(`   🔍 SEO: ${issue}`);
+  }
+}
+
+console.log(`\n${"═".repeat(70)}`);
+const avg = results.reduce((t, r) => t + r.a11yScore, 0) / results.length;
+console.log(`Average a11y score: ${avg.toFixed(3)}`);
+console.log(failed ? "\n❌ FAIL — fix the issues above, redeploy, and re-run." : "\n✅ PASS");
+
+process.exit(failed ? 1 : 0);

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

package/dist/kiro/.kiro/skills/jahia-jcr-sql2/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: jahia-jcr-sql2
+description: JCR-SQL2 reference for Jahia queries. Use when building, reviewing, or debugging SQL2 statements for content listings, full-text search, sorting, pagination, or Java back-end query code.
+---
+
+# Skill: jahia-jcr-sql2
+
+Use this skill when you need the JCR-SQL2 language itself: selectors, path constraints, filters, ordering, full-text syntax, joins, pagination rules, and performance guardrails.
+
+---
+
+## When to use JCR-SQL2
+
+JCR-SQL2 is the standard Jahia query language for:
+
+- listing pages or content with filtering and sorting
+- querying a folder subtree
+- searching by property value, date, or reference
+- full-text search across indexed content
+- back-end Java code using `QueryManagerWrapper`
+- template-set listings that use `useJCRQuery` or the Page Builder query component
+
+---
+
+## Basic syntax
+
+### Select by node type
+
+```sql
+SELECT * FROM [jnt:page] AS page
+SELECT * FROM [jnt:content] AS content
+SELECT * FROM [jnt:file] AS file
+```
+
+The selector matches the named type and its subtypes.
+
+### Common node types
+
+| Type | Meaning |
+|------|---------|
+| `jnt:page` | pages |
+| `jnt:content` | editorial content |
+| `jnt:file` | files |
+| `jnt:virtualsite` | sites |
+| `jmix:searchable` | general searchable content |
+| `nt:base` | all nodes — avoid unless paired with a strict path |
+
+---
+
+## Path constraints
+
+### Recursive subtree
+
+```sql
+SELECT * FROM [jnt:page] AS page
+WHERE ISDESCENDANTNODE(page, '/sites/luxe/home')
+```
+
+### Direct children only
+
+```sql
+SELECT * FROM [jnt:page] AS page
+WHERE ISCHILDNODE(page, '/sites/luxe/home')
+```
+
+**Guardrail:** always constrain by path to avoid repository-wide scans.
+
+---
+
+## Property constraints
+
+### Exact match
+
+```sql
+WHERE page.[j:templateName] = 'home'
+WHERE node.[jcr:title] = 'My Title'
+```
+
+### Pattern match
+
+```sql
+WHERE node.[jcr:title] LIKE '%keyword%'
+WHERE node.[j:nodename] LIKE '%.png'
+```
+
+### Null checks
+
+```sql
+WHERE page.[jcr:title] IS NOT NULL
+```
+
+### Boolean
+
+```sql
+WHERE node.[j:published] = CAST('true' AS BOOLEAN)
+```
+
+### Date comparison
+
+```sql
+WHERE page.[jcr:lastModified] > CAST('2026-01-01T00:00:00.000Z' AS DATE)
+```
+
+Use the millisecond form `yyyy-MM-dd'T'HH:mm:ss.SSSX` for SQL2 date casts.
+
+### Multiple conditions
+
+```sql
+WHERE ISDESCENDANTNODE(page, '/sites/luxe')
+  AND page.[jcr:lastModified] > CAST('2026-01-01T00:00:00.000Z' AS DATE)
+```
+
+### OR conditions
+
+```sql
+WHERE node.[jcr:primaryType] = 'jnt:bigText'
+   OR node.[jcr:primaryType] = 'jnt:article'
+```
+
+---
+
+## Ordering
+
+```sql
+ORDER BY page.[jcr:lastModified] DESC
+ORDER BY page.[jcr:created] ASC
+ORDER BY node.[jcr:title]
+```
+
+Multiple columns:
+
+```sql
+ORDER BY page.[j:templateName] ASC, page.[jcr:lastModified] DESC
+```
+
+---
+
+## Full-text search
+
+### Search indexed content
+
+```sql
+WHERE CONTAINS(node.*, 'digital')
+```
+
+### Search one property
+
+```sql
+WHERE CONTAINS(node.[jcr:title], 'welcome')
+```
+
+### Expression syntax
+
+| Syntax | Meaning |
+|--------|---------|
+| `term` | must contain the term |
+| `term1 term2` | implicit AND |
+| `term1 OR term2` | either term |
+| `"exact phrase"` | exact phrase |
+| `-term` | exclude term |
+
+### Relevance sort
+
+```sql
+SELECT * FROM [jnt:content] AS n
+WHERE ISDESCENDANTNODE(n, '/sites/luxe')
+  AND CONTAINS(n.*, 'digital')
+ORDER BY SCORE(n) DESC
+```
+
+Combine full-text with path constraints for performance.
+
+---
+
+## Joins
+
+```sql
+SELECT * FROM [jnt:imageReferenceLink] AS img
+INNER JOIN [jnt:file] AS file
+ON img.[j:node] = file.[jcr:uuid]
+WHERE img.[j:node] = 'UUID'
+```
+
+Jahia supports inner joins, but keep them focused and path-constrained whenever possible.
+
+---
+
+## Using SQL2 in Jahia code
+
+### Template-set listing with `useJCRQuery`
+
+```tsx
+const posts = useJCRQuery({
+  query: `SELECT * FROM [namespace:blogPost] AS post
+          WHERE ISDESCENDANTNODE(post, '/sites/${siteKey}/contents/blog')
+          ORDER BY post.[publicationDate] DESC`,
+});
+```
+
+### Java back-end query execution
+
+```java
+QueryManagerWrapper qm = session.getWorkspace().getQueryManager();
+QueryWrapper query = qm.createQuery(sql2Statement, Query.JCR_SQL2);
+query.setLimit(limit);
+query.setOffset(offset);
+JCRNodeIteratorWrapper nodes = query.execute().getNodes();
+```
+
+**Guardrail:** never embed `LIMIT` or `OFFSET` inside the SQL2 string. Use `setLimit()` and `setOffset()`.
+
+---
+
+## Security and validation
+
+### Escape user input
+
+In Java back-end code, escape user-provided values with `JCRContentUtils.sqlEncode()` before interpolating them into a SQL2 string.
+
+```java
+String safeValue = JCRContentUtils.sqlEncode(userInput);
+```
+
+### Validate dynamic sort fields
+
+If a user can choose the sort field, validate it against a whitelist before interpolating it into `ORDER BY`.
+
+---
+
+## Performance best practices
+
+1. Always constrain by path.
+2. Use the most specific node type possible.
+3. Keep result sets small.
+4. Prefer indexed equality filters over broad `LIKE '%...%'` patterns.
+5. Use full-text sparingly on large trees.
+6. Sort on common indexed fields such as `jcr:lastModified` or `jcr:created`.
+7. Cap API result limits to a sane maximum.
+
+---
+
+## Quick checklist
+
+- [ ] Query has a path constraint
+- [ ] Node type is specific
+- [ ] Sort field is intentional and safe
+- [ ] Full-text is combined with a subtree path
+- [ ] Dates use `yyyy-MM-dd'T'HH:mm:ss.SSSX`
+- [ ] Java code uses `setLimit()` and `setOffset()` instead of inline SQL clauses
+
+---
+
+## Related skills
+
+- `/jahia-dev-query-content` — apply SQL2 inside Page Builder queries and JS module views
+- `/jahia-dev-define-content-type` — define the content types you will query
+- `/jahia-java-jcr` — implement back-end JCR logic around the query
+