@jahia/agentic 0.0.0

package/dist/claude/.claude/skills/jahia-dev/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: jahia-dev
+description: Entry point for Jahia JavaScript module development. Detects your project state and tells you what to do next. Start here if you are new to the project or unsure what skill to use.
+---
+
+# Jahia Dev — Project GPS
+
+You are the entry point for Jahia JavaScript module development. Your job is to assess the current project state and guide the user to the right next skill.
+
+## Step 1 — Detect project state
+
+Run all checks in parallel.
+
+### 1. Module exists?
+
+Search for a `package.json` that references `@jahia/javascript-modules-library` in the current directory or subdirectories:
+
+```bash
+find . -name "package.json" -not -path "*/node_modules/*" | xargs grep -l "@jahia/javascript-modules-library" 2>/dev/null | head -5
+```
+
+- Found → record the module name (from the `name` field in that `package.json`)
+- Not found → module does not exist yet
+
+### 2. Jahia running?
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/cms/login
+```
+
+- `200` → Jahia is running at `http://localhost:8080`
+- Anything else → Jahia is not running
+
+### 3. Content types defined?
+
+```bash
+find src/components -name "definition.cnd" 2>/dev/null | wc -l
+```
+
+Record the count of `.cnd` files found under `src/components`.
+
+### 4. Views defined?
+
+```bash
+find src/components -name "*.server.tsx" -o -name "*.client.tsx" 2>/dev/null | wc -l
+```
+
+Record the count of view files found.
+
+### 5. Page templates defined?
+
+```bash
+find src/templates/Page -type f 2>/dev/null | wc -l
+```
+
+Record the count of files in `src/templates/Page/`. More than 1 means custom templates exist (the default `index.server.tsx` is always present).
+
+---
+
+## Step 2 — Report project state to user
+
+Print a clear, scannable status summary:
+
+```
+📦 Module:          ✅ <module-name> (found)   OR   ❌ not found
+🐳 Jahia:           ✅ running at http://localhost:8080   OR   ❌ not running
+📋 Content types:   <N> defined
+🖼  Views:          <N> defined
+📄 Page templates:  <N> defined
+```
+
+---
+
+## Step 3 — Recommend next action
+
+Use the matrix below to pick exactly one recommendation to highlight:
+
+| Condition | Recommendation |
+|-----------|---------------|
+| No module found | 🚀 **Start here:** invoke `/jahia-dev-create-template-set` to scaffold a new Jahia JavaScript module. |
+| Module found, Jahia not running | 🐳 Your module is ready. Invoke `/jahia-dev-start-local` to start Jahia locally (Docker recommended). |
+| Module + Jahia running, 0 content types | 🎯 Jahia is running! Time to build your first component. Invoke `/jahia-dev-build-component` to create a content type + view. |
+| Module + Jahia running, content types exist, ≤1 page template | 📐 You have components. Invoke `/jahia-dev-create-page-template` to create a page template and start assembling pages. |
+| Module + Jahia running, templates exist (>1) | 🏗 Your module is taking shape! Choose what to do next (see options below). |
+
+When the last condition applies, present all options:
+
+```
+🏗 Your module is taking shape! What would you like to do next?
+  - Add a new component         → /jahia-dev-build-component
+  - Create a content listing    → /jahia-dev-query-content
+  - Review your code for issues → /jahia-dev-review
+  - Screenshot a reference site → /jahia-dev-screenshot
+  - Create a new page template  → /jahia-dev-create-page-template
+  - Clean up boilerplate        → run /jahia-dev-review and look for S10
+```
+
+---
+
+## Step 4 — Print the full skill map
+
+Always print this at the end so the user can navigate anywhere:
+
+```
+## Jahia Development Skills
+
+### Setup
+/jahia-dev-create-template-set   Scaffold a new JS/React module
+/jahia-dev-start-local           Start Jahia locally (Docker or bare metal)
+
+### Building
+/jahia-dev-build-component       Build a complete component (content type + view) ← start here
+/jahia-dev-define-content-type   Define a CND content type and types.ts
+/jahia-dev-create-view           Implement a React view (.server.tsx or .client.tsx Island)
+/jahia-dev-create-page-template  Create a page template with Areas
+
+### Content
+/jahia-dev-query-content         Query JCR content with JCR-SQL2 or useJCRQuery
+
+### Quality
+/jahia-dev-review                Review code for Jahia and generic best practices
+/jahia-dev-screenshot            Screenshot reference URL + Jahia render for visual comparison
+/jahia-dev-debug                 Debug build/deploy/runtime errors end-to-end
+```

package/dist/claude/.claude/skills/jahia-dev-accessibility/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: jahia-dev-accessibility
+description: Audits a Jahia JS module for WCAG 2.1 AA accessibility violations using axe-core and Playwright. Runs automated checks against all live pages, reports violations by severity, and fixes them in the React views and CSS. Invoke after building components or before final review.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# Skill: jahia-dev-accessibility
+
+Runs a live accessibility audit against all published pages of the site, reports violations, and fixes them in the source code.
+
+---
+
+## Step 1 — Confirm pages are live
+
+You need the list of public page URLs. Look for `pages.json` in the module root first:
+
+```bash
+cat pages.json 2>/dev/null || echo "not found"
+```
+
+If absent, derive URLs from the site structure or ask the user. All pages must be accessible at `http://localhost:8080`.
+
+---
+
+## Step 2 — Install audit tooling
+
+Check if `@axe-core/playwright` and `playwright` are available:
+
+```bash
+node -e "require('@axe-core/playwright'); require('playwright'); console.log('ok')" 2>/dev/null || echo "missing"
+```
+
+If missing, install temporarily (project-local, not committed):
+
+```bash
+npm install --no-save @axe-core/playwright playwright
+npx playwright install chromium --with-deps
+```
+
+---
+
+## Step 3 — Run the audit
+
+Save this script as `/tmp/a11y-audit.mjs` and run it:
+
+```js
+import { chromium } from "playwright";
+import { AxeBuilder } from "@axe-core/playwright";
+import { readFileSync } from "fs";
+
+const urls = JSON.parse(readFileSync("pages.json", "utf-8"));
+
+const browser = await chromium.launch({ args: ["--no-sandbox"] });
+const page = await browser.newPage();
+
+for (const url of urls) {
+  console.log(`\n${"=".repeat(60)}\nAuditing: ${url}\n${"=".repeat(60)}`);
+  await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
+
+  const results = await new AxeBuilder({ page })
+    .withTags(["wcag2a", "wcag2aa", "wcag21aa"])
+    .analyze();
+
+  if (results.violations.length === 0) {
+    console.log("✅ No violations found.");
+    continue;
+  }
+
+  for (const v of results.violations) {
+    console.log(`\n[${v.impact?.toUpperCase()}] ${v.id}: ${v.description}`);
+    console.log(`Help: ${v.helpUrl}`);
+    for (const node of v.nodes) {
+      console.log(`  Target: ${node.target.join(" > ")}`);
+      console.log(`  HTML:   ${node.html}`);
+      if (node.failureSummary) {
+        console.log(`  Fix:    ${node.failureSummary}`);
+      }
+    }
+  }
+}
+
+await browser.close();
+```
+
+```bash
+node /tmp/a11y-audit.mjs 2>&1 | tee /tmp/a11y-report.txt
+```
+
+---
+
+## Step 4 — Interpret results
+
+Group violations by impact. Focus on `critical` and `serious` first — they contribute most to a poor score.
+
+Common violations in Jahia JS modules and their fixes:
+
+### 🔴 Critical / Serious
+
+**`color-contrast`** — text fails WCAG AA contrast ratio (4.5:1 for normal text, 3:1 for large text)
+```css
+/* Bad */
+color: #aaa; background: #fff;
+
+/* Fix — use a contrast checker: https://webaim.org/resources/contrastchecker/ */
+color: #595959; /* 7:1 ratio on white */
+```
+
+**`image-alt`** — `<img>` missing `alt` attribute
+```tsx
+/* Bad */
+<img src={buildNodeUrl(props.image)} />
+
+/* Fix — use content from CND, fall back to empty string for decorative */
+<img src={buildNodeUrl(props.image)} alt={props.imageAlt ?? ""} />
+```
+Add `- imageAlt (string) i18n` to the CND and `imageAlt?: string` to `types.ts`.
+
+**`button-name`** — `<button>` or `<a>` is empty (icon-only without label)
+```tsx
+/* Bad */
+<button><svg>...</svg></button>
+
+/* Fix */
+<button aria-label="Open menu"><svg aria-hidden="true">...</svg></button>
+```
+
+**`landmark-one-main`** — page has no `<main>` landmark
+```tsx
+/* Fix — wrap page content in <main> */
+<main id="main-content">
+  {/* page content */}
+</main>
+```
+
+**`page-has-heading-one`** — page has no `<h1>` element
+```tsx
+/* Fix — ensure the hero or first section renders an <h1> */
+<h1>{props.title}</h1>
+```
+
+**`link-name`** — `<a>` with no accessible text
+```tsx
+/* Bad */
+<a href={url}><img src="..." /></a>
+
+/* Fix */
+<a href={url}><img src="..." alt={props.linkLabel ?? "Learn more"} /></a>
+```
+
+### 🟡 Moderate
+
+**`heading-order`** — headings skip levels (e.g. `<h1>` → `<h3>`)
+```tsx
+/* Review: the first heading in a component should be h2 (after the page h1) */
+/* Section titles: h2, subsections: h3 */
+```
+
+**`region`** — content is outside landmark regions  
+Wrap page sections in semantic elements: `<header>`, `<nav>`, `<main>`, `<footer>`, `<section aria-label="...">`.
+
+**`list`** — `<ul>` or `<ol>` contains elements other than `<li>`
+```tsx
+/* Bad */
+<ul>
+  <div>item</div>
+</ul>
+
+/* Fix */
+<ul>
+  <li>item</li>
+</ul>
+```
+
+**`html-has-lang`** — `<html>` element missing `lang` attribute  
+This is set at the page template level. Verify the template registered in `src/templates/` includes `lang`:
+```tsx
+/* In the page template */
+<html lang={currentLanguage ?? "en"}>
+```
+Jahia provides the language via `useServerContext()`:
+```tsx
+import { useServerContext } from "@jahia/javascript-modules-library";
+const { currentLanguage } = useServerContext();
+```
+
+**`aria-required-children`** — ARIA role is missing required children  
+Avoid misusing ARIA roles. Prefer native HTML elements (`<ul>/<li>`, `<table>/<tr>/<td>`).
+
+---
+
+## Step 5 — Fix in source
+
+For each violation:
+
+1. Identify the component: match `node.target` HTML to a `.server.tsx` file
+2. Edit the view to apply the fix
+3. If the fix requires a new CND field (e.g. `imageAlt`), update `definition.cnd` and `types.ts`
+4. Run `yarn build && yarn jahia-deploy`
+
+After all fixes:
+
+```bash
+# Re-run the audit to verify violations are resolved
+node /tmp/a11y-audit.mjs 2>&1 | grep -E "(CRITICAL|SERIOUS|MODERATE|No violations)"
+```
+
+Iterate until only `minor` violations remain (or none).
+
+---
+
+## Step 6 — Proactive checks beyond axe-core
+
+axe-core catches ~30–40% of WCAG issues automatically. Also check manually:
+
+- **Keyboard navigation**: can every interactive element (link, button, form field) be reached with Tab?
+- **Focus indicators**: is `:focus` visible on all interactive elements?
+  ```css
+  /* Ensure focus ring is never suppressed globally */
+  /* Bad */
+  * { outline: none; }
+  /* Fix — use :focus-visible */
+  :focus-visible { outline: 2px solid #0969da; outline-offset: 2px; }
+  ```
+- **Skip link**: add a "Skip to main content" link as the first focusable element
+  ```tsx
+  <a href="#main-content" className={styles.skipLink}>Skip to main content</a>
+  ```
+  ```css
+  .skipLink {
+    position: absolute;
+    top: -100%;
+    left: 0;
+    background: #000;
+    color: #fff;
+    padding: 8px 16px;
+    z-index: 999;
+  }
+  .skipLink:focus { top: 0; }
+  ```
+- **Motion**: if any CSS animation exists, wrap it in `@media (prefers-reduced-motion: no-preference)`
+- **Touch targets**: interactive elements should be at least 44×44px
+
+---
+
+## Step 7 — Report summary
+
+After fixing, report:
+
+```
+## Accessibility Audit Summary
+
+Pages audited: N
+Violations fixed:
+  - [critical] color-contrast: 3 instances → fixed (updated CSS contrast ratios)
+  - [serious] image-alt: 2 instances → fixed (added imageAlt CND field)
+  - [serious] button-name: 1 instance → fixed (added aria-label to icon button)
+  - [moderate] heading-order: 2 instances → fixed (restructured h2/h3 hierarchy)
+
+Remaining violations: N (all minor / informational)
+
+Axe tags checked: wcag2a, wcag2aa, wcag21aa
+```
+
+---
+
+## References
+
+- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
+- axe-core rules: https://dequeuniversity.com/rules/axe/
+- WCAG 2.1 Quick Ref: https://www.w3.org/WAI/WCAG21/quickref/
+- MDN ARIA: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA

package/dist/claude/.claude/skills/jahia-dev-apis/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: jahia-dev-apis
+description: >
+  Jahia 8.2 developer API reference covering GraphQL, JCR Java API, RESTful JCR access,
+  OAuth/SAML authentication, personal API tokens, HTML filtering, and Content Security Policy.
+
+  Trigger this skill when the user is:
+  - Working with the Jahia GraphQL API (queries, mutations, schema extensions, Apollo client)
+  - Using the JCR Java API to read/write content nodes
+  - Accessing the RESTful JCR API or building JAX-RS endpoints
+  - Setting up OAuth 2.0 (social login) or building a custom OAuth connector
+  - Configuring SAML 2.0 authentication
+  - Using the UPA (username/password + MFA) authentication module
+  - Creating or using personal API tokens
+  - Configuring HTML filtering (XSS protection) for content properties
+  - Setting up a Content Security Policy (CSP) for a Jahia site
+  - Configuring the security filter/service (API authorization, CORS, scopes)
+  - Asking which Jahia API to use (GraphQL vs REST vs Actions)
+allowed-tools: Read
+---
+
+# Jahia 8.2 Developer APIs
+
+This skill covers all developer-facing APIs and security configuration in Jahia 8.2.
+
+## Reference files
+
+| File | When to use |
+|------|-------------|
+| `references/graphql.md` | GraphQL endpoint URL, JCR queries/mutations, schema extension (SDL + Java), connection/pagination pattern, Apollo client setup, CORS and auth config |
+| `references/jcr-api.md` | Java JCR Session API (read/write nodes), auto-splitting, property interceptors, RESTful JCR access (REST endpoints, HAL+JSON), JAX-RS endpoint registration, Actions (legacy) |
+| `references/authentication.md` | OAuth 2.0 social login modules, building a custom OAuth connector, SAML 2.0 setup, UPA (username/password + MFA) module, personal API tokens (create/use/manage via Groovy) |
+| `references/security.md` | Security filter/service (scope-based authorization config), HTML filtering v2 (YAML config, strategies, workspace rules), Content Security Policy setup, JahiaUserManagerService |
+
+## Quick API overview
+
+| API | Endpoint / Access | Primary use case |
+|-----|-------------------|------------------|
+| GraphQL | `POST /modules/graphql` | Client-side apps, SPA; flexible queries, mutations, JCR node access, custom schema extension |
+| RESTful JCR | `GET/PUT/DELETE /modules/api/jcr/v1/{workspace}/{lang}/nodes/{id}` | CRUD on JCR nodes via HTTP; useful for automation scripts and server-to-server calls |
+| JAX-RS (custom REST) | Registered under `/modules/{alias}` via OSGi bundle directives | Custom REST endpoints packaged as Jahia modules |
+| JCR Java API | `JCRTemplate.getInstance().doExecuteWithSystemSession(...)` | Server-side Java code; direct node manipulation inside modules |
+| Actions | `POST /{path}.{actionName}.do` | Legacy: simple isolated server-side operations triggered from forms or rules |
+| Personal API tokens | `Authorization: APIToken <token>` header | Authenticate API calls without credentials; scoped access |
+| JWT tokens | `Authorization: Bearer <token>` header | Deprecated — use personal API tokens instead |
+
+## Key Jahia-specific concepts
+
+- **Workspaces**: `EDIT` (default) and `LIVE`. GraphQL queries default to `EDIT`; specify `jcr(workspace: LIVE)` for published content.
+- **Security filter**: All APIs (GraphQL, REST, views) are closed by default. Access is granted via scope-based config files in `karaf/etc` with pattern `org.jahia.bundles.api.authorization-*.yml`.
+- **Internationalization**: JCR sessions are opened in one language; GraphQL can query multiple languages in one call using `language:` arguments on individual fields.
+- **Session save**: Every JCR write must end with `session.save()`. In GraphQL mutations, save is automatic at the end of each `mutation { jcr }` block.