@jahia/agentic 0.3.0 → 0.4.0

package/dist/gemini/.agents/skills/jahia-orchestrate/scripts/verify-pages.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const pagesFile = "pages.json";
+let urls;
+try {
+  urls = JSON.parse(readFileSync(pagesFile, "utf8"));
+} catch {
+  console.error(`MISSING: ${pagesFile} not found or invalid JSON`);
+  process.exit(1);
+}
+
+if (!Array.isArray(urls) || urls.length === 0) {
+  console.error(`EMPTY: ${pagesFile} contains no URLs`);
+  process.exit(1);
+}
+
+const tmp = join(tmpdir(), "jahia_pg_verify.html");
+let allOk = true;
+
+for (const url of urls) {
+  let code, body;
+  try {
+    code = execSync(`curl -s -o "${tmp}" -w "%{http_code}" "${url}"`, { encoding: "utf8" }).trim();
+    body = readFileSync(tmp, "utf8");
+  } catch {
+    console.log(`ERROR [unknown] ${url}`);
+    allOk = false;
+    continue;
+  }
+  const titleMatch = body.match(/<title>([^<]*)<\/title>/i);
+  const title = titleMatch ? titleMatch[1].trim() : "";
+  const hasError =
+    body.includes("error details are shown in development mode") ||
+    body.includes("pl.touk.throwing");
+
+  let status;
+  if (hasError) {
+    status = "ERROR_PAGE";
+  } else if (code !== "200") {
+    status = `HTTP_${code}`;
+  } else {
+    const mainMatch = body.match(/<main[^>]*>([\s\S]*?)<\/main>/i);
+    if (mainMatch) {
+      const mainText = mainMatch[1].replace(/<[^>]+>/g, "").replace(/\s+/g, " ").trim();
+      status = mainText.length < 150 ? "INCOMPLETE" : "OK";
+    } else {
+      status = "OK";
+    }
+  }
+
+  console.log(`${status} [${title}] ${url}`);
+  if (status !== "OK") allOk = false;
+}
+
+process.exit(allOk ? 0 : 1);

package/dist/gemini/AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md
 <!-- Generated by APM CLI from distributed .apm/ primitives -->
-<!-- Build ID: 971609428c97 -->
-<!-- APM Version: 0.20.0 -->
+<!-- Build ID: 4b60eae51ba0 -->
+<!-- APM Version: 0.21.0 -->
 
 ## Global Instructions
 
@@ -14,15 +14,22 @@ You are helping develop a **Jahia JavaScript Module** — a React-based template
 ## Agent Principles
 
 1. **Always invoke a skill before any Jahia task** — skills are the canonical source of patterns, gotchas, and API syntax. Never operate from memory alone.
+1a. **Always load CND reference files before writing any CND** — Jahia-specific patterns (`choicelist[linkTypeInitializer]`, `mix:title`, child nodes for CTAs, `jmix:image` weakreferences) are not in your training data. Before writing any CND, read the reference files: `find . -maxdepth 4 -name 'cnd-jahia-mixins*' | head -3`. When working interactively through skill chains, prefer `@jahia-cnd-author` (it loads these files for you).
 2. **Never use `yarn dev` from an agent** — it is an interactive file watcher for human developers only. Always deploy with `yarn build && yarn jahia-deploy` (one-shot, non-interactive).
+2a. **Use the TypeScript LSP for API discovery, never grep.** When you need to know a function's signature or what a module exports, call `mcp__ide__getDiagnostics` on the file after writing it — the LSP reads live type definitions and reports mismatches, wrong argument counts, and missing exports. Never run `grep` on `node_modules` to find a function name or signature.
 3. **Never hardcode URLs** — all navigable links must come from contributed content (JCR nodes, `j:linkType`, `buildNodeUrl`). This is a CMS: content owns the URLs.
 4. **Never use `j:linkType: "external"` for internal pages** — use `"internal"` + `j:linknode`. External URLs break on environment changes, language switches, and vanity URL rewrites.
-5. **Always verify before creating** — check that content types are deployed, site keys are correct, and area structures exist before attempting GraphQL mutations.
+5. **Always verify before creating** — check that content types are deployed, site keys are correct, and parent area nodes exist before creating content via MCP.
 6. **All props are optional at runtime** — even mandatory CND fields. Always guard against `undefined` in views.
-7. **Always include `-H "Origin: http://localhost:8080"` in every GraphQL curl** — omitting it returns `Permission denied` even with correct credentials.
-8. **Build accessible HTML from the start** — every view must use semantic HTML (`<main>`, `<header>`, `<nav>`, `<footer>`, `<section>`, `<article>`), include exactly one `<h1>` per page, use a strict heading hierarchy (h1 → h2 → h3), add `alt` text to every `<img>`, and use sufficient colour contrast (≥ 4.5:1 for body text). Baking this in during authoring is faster than a post-hoc audit.
-9. **Run one accessibility audit at the end** — after all components are built and content is published, invoke `/jahia-dev-accessibility` once to catch any remaining violations. Do not audit after every individual component; it wastes time on pages that are not yet complete.
-10. **Batch builds and deploys** — build all components together, then run `yarn build && yarn jahia-deploy` once rather than after each individual component. Deploy once before populating content.
+7. **Use MCP tools for all Jahia operations — never GraphQL curl.** The `jahia` MCP server covers site, page, content, and publication operations. Never fall back to `curl` + GraphQL mutations for anything the MCP server can do. Never write Python scripts — use JavaScript or bash only.
+7a. **`yarn` and `npx` must be run from the module root** — the module is a standalone project, not part of a monorepo. Running `yarn` from a parent directory fails with a workspace boundary error. Always `cd` to the module directory first.
+7b. **Use `grep`, not `ugrep`** — `ugrep` is not available on all systems and does not support the same regex syntax. Use `grep -rn` for plain text, `grep -rn -E` for extended regex, or `grep -rn -P` for Perl-compatible patterns (e.g. lookaheads). Never use `ugrep` or `(?m)` flags.
+8. **Build accessible HTML from the start** — every view must use semantic HTML (`<main>`, `<header>`, `<nav>`, `<footer>`, `<section>`, `<article>`), include exactly one `<h1>` per page (in the template from `jcr:title` — never inside a component), use a strict heading hierarchy (h1 in template → h2 in components → h3 for sub-items), add `alt` text to every `<img>` with a meaningful fallback (`imageAlt || title || 'Image'` — never empty string), ensure sufficient colour contrast (≥ 4.5:1 for body text), include a skip link at the top of the template, and never leave a landmark (`<nav>`, `<footer>`) empty.
+9. **Review quality after each deploy** — after deploying and populating content, run `/jahia-dev-site-review` to get a scored a11y + SEO report. Fix any critical/serious violations before moving on. Do not write `pages.json` until the review passes.
+10. **Deploy iteratively** — deploy after each component with `yarn build && yarn jahia-deploy`, verify it renders, then move to the next. Don't accumulate components before deploying; a broken component is easier to diagnose in isolation.
+11. **Collocate everything per component** — each component lives in `src/components/<Category>/<Name>/` containing its `definition.cnd`, `default.server.tsx`, `component.module.css`, and `types.ts`. Never centralize content types in `settings/definitions.cnd` — that file holds only namespace declarations and the module base mixin.
+12. **Always build a page template first** — every website needs a root template at `src/templates/<ModuleName>Template/default.server.tsx`. It must include: a skip link, a `<nav>` built inline from children of the site's home node using `getChildNodes(renderContext.getSite().getNode('home'), -1, 0, n => n.isNodeType('jnt:page'))` (pages live under `home`, not directly under the site), a `<main id="main-content">` with `<h1>{title}</h1>` and Areas, and a `<footer>` that is never empty. The `<title>` tag must be `{title} | {siteName}` — never set `jcr:title` to the full `Page | Site` string; `jcr:title` is always just the short page name (e.g. "Car Insurance"). Build and deploy before any page-specific components.
+13. **SEO baseline** — every page template must render a `<title>` tag, all `<img>` must have descriptive `alt` text, all links must have visible text (no icon-only links without `aria-label`), and pages must have a single `<h1>` matching the page title.
 
 ## Skill Map
 
@@ -37,11 +44,13 @@ Start with `/jahia` if unsure where to begin.
 | `/jahia-dev-start-local` | Start Jahia locally (Docker or bare metal) |
 | `/jahia-dev-build-component` | Build a complete component (CND + view) — start here |
 | `/jahia-dev-define-content-type` | Define a CND content type + types.ts |
+| `/jahia-dev-review-cnd` | Validate a CND file for antipatterns — run after writing any CND |
 | `/jahia-dev-create-view` | Implement a React view (.server.tsx + CSS Module) |
 | `/jahia-dev-create-page-template` | Create a page template with Areas |
 | `/jahia-dev-query-content` | Write JCR-SQL2 queries and useJCRQuery |
 | `/jahia-dev-review` | Code review: 8 critical checks, 9 warnings, 11 suggestions |
-| `/jahia-dev-accessibility` | Audit live pages with axe-core, fix WCAG 2.1 AA violations |
+| `/jahia-dev-site-review` | Scored a11y + SEO report on live pages — use after every deploy |
+| `/jahia-dev-accessibility` | Deep WCAG 2.1 AA audit with fixes — use for targeted a11y work |
 | `/jahia-dev-screenshot` | Screenshot reference + local render for visual comparison |
 | `/jahia-dev-debug` | Debug build/deploy/runtime errors end-to-end |
 

package/dist/gemini/GEMINI.md

@@ -1,6 +1,6 @@
 # GEMINI.md
 <!-- Generated by APM CLI -->
-<!-- Build ID: 9f2e76a3c166 -->
-<!-- APM Version: 0.20.0 -->
+<!-- Build ID: 2ff1bbd97c77 -->
+<!-- APM Version: 0.21.0 -->
 
 @./AGENTS.md

package/dist/index.js

@@ -969,6 +969,19 @@ if (interactive && overwriteCount > 0) {
 } else if (overwriteCount > 0) R.warn(`Harness already exists, ${overwriteCount} file${overwriteCount >= 2 ? "s" : ""} will be overwritten.`);
 for (const dir of dirsToCreate) mkdirSync(dir, { recursive: true });
 for (const { src, dst } of filesToCopy) copyFileSync(src, dst);
+if (target === "claude" && !process.env.CI) {
+	R.step("Installing TypeScript LSP plugin for Claude Code…");
+	const pluginInstall = spawnSync("claude", [
+		"plugin",
+		"install",
+		"typescript-lsp@claude-plugins-official"
+	], {
+		encoding: "utf-8",
+		timeout: 15e3
+	});
+	if (pluginInstall.error || pluginInstall.status !== 0) R.warn(`Could not install TypeScript LSP plugin automatically.\nRun manually: ${styleText("blueBright", "claude plugin install typescript-lsp@claude-plugins-official")}`);
+	else R.success("TypeScript LSP plugin installed.");
+}
 ye(`Harness created successfully!
 
 To update the harness in the future, run ${styleText("blueBright", "npx @jahia/agentic@latest " + target)}`);

package/dist/opencode/.agents/skills/jahia/SKILL.md

@@ -88,7 +88,11 @@ Use these recipes as starting points when the task maps to a known pattern.
 ```
 1. /jahia-dev-create-template-set   → scaffold the module
 2. /jahia-dev-start-local           → start Jahia locally
-3. /jahia-dev-build-component       → build content types + views (repeat per component)
+3. /jahia-dev-build-component       → build ONE component at a time (repeat this step per component):
+                                       - invokes /jahia-dev-define-content-type
+                                       - which invokes @jahia-cnd-author (sub-agent, mandatory)
+                                       - then invokes /jahia-dev-create-view
+                                       ⚠ Never batch-write CND — always go through @jahia-cnd-author
 4. /jahia-dev-create-page-template  → create page templates
 5. /jahia-content-create-content    → use `site.templateSets` + `site.create`, then add pages and content
 6. /jahia-content-publish           → publish the site content

package/dist/opencode/.agents/skills/jahia-dev-accessibility/SKILL.md

@@ -110,10 +110,10 @@ color: #595959; /* 7:1 ratio on white */
 /* 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 ?? ""} />
+/* Fix — use the image node's jcr:title, fall back to empty string for decorative */
+<img src={buildNodeUrl(props.image)} alt={props.image?.getPropertyAsString("jcr:title") ?? ""} />
 ```
-Add `- imageAlt (string) i18n` to the CND and `imageAlt?: string` to `types.ts`.
+The image node already has `jcr:title` (from `mix:title`). **Do not add `imageAlt (string) i18n`** to the CND.
 
 **`button-name`** — `<button>` or `<a>` is empty (icon-only without label)
 ```tsx

package/dist/opencode/.agents/skills/jahia-dev-build-component/SKILL.md

@@ -43,15 +43,18 @@ Has children: <yes: ChildType / no>
 
 ---
 
-## Step 2 — Invoke `jahia-dev-define-content-type`
+## Step 2 — REQUIRED: Invoke `/jahia-dev-define-content-type`
 
-Use the instructions from the `jahia-dev-define-content-type` skill to:
+**Do not write CND manually.** Jahia-specific patterns (`choicelist[linkTypeInitializer]`, `mix:title`, child nodes for CTAs) are not in LLM training data — writing CND from memory always produces broken output. This skill delegates to `@jahia-cnd-author` which loads the correct reference files.
 
-1. Identify the namespace (check `settings/definitions.cnd`)
-2. Create `src/components/<Category>/<Name>/definition.cnd`
-3. Create `src/components/<Category>/<Name>/types.ts`
-4. Run `yarn build && yarn jahia-deploy` to push the type to Jahia
-5. Verify the content type appears in the Jahia content editor
+Invoke `/jahia-dev-define-content-type` in a sub-agent job. Pass the component spec. Wait for it to confirm PASS before continuing.
+
+The skill will:
+1. Confirm the namespace (from `settings/definitions.cnd`)
+2. Invoke `@jahia-cnd-author` to create `src/components/<Category>/<Name>/definition.cnd`
+3. Invoke `@jahia-cnd-author` to create `src/components/<Category>/<Name>/types.ts`
+
+**Do not proceed to Step 3 until the CND review is PASS.**
 
 ---
 

package/dist/opencode/.agents/skills/jahia-dev-create-page-template/SKILL.md

@@ -14,35 +14,72 @@ A **page template** defines the full layout of a page. It is registered with `co
 
 ## Step 1 — Create the template file
 
-Page templates live in `src/templates/Page/`. Name the file `<templateName>.server.tsx`.
+Page templates live in `src/templates/<ModuleName>Template/`. Name the file `default.server.tsx`.
 
 ```tsx
-import { Area, AbsoluteArea, jahiaComponent } from "@jahia/javascript-modules-library";
-import { Layout } from "../Layout.jsx";
+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: "Single Column",
-    name: "singleColumn",        // used in Jahia UI when selecting a template
+    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>
+    );
   },
-  ({ "jcr:title": title }, { renderContext }) => (
-    <Layout title={title}>
-      <Area name="header" nodeType="namespace:header" />
-      <main style={{ maxWidth: "40rem", margin: "0 auto" }}>
-        <Area name="main" />
-      </main>
-      <AbsoluteArea
-        name="footer"
-        parent={renderContext.getSite()}
-        nodeType="namespace:footer"
-      />
-    </Layout>
-  ),
 );
 ```
 
+
 ---
 
 ## Step 2 — Choose: Area vs AbsoluteArea
@@ -266,13 +303,14 @@ After deploying, the new template will appear in the **template selection** step
 ---
 
 ## Validation checklist
-- [ ] File is in `src/templates/Page/`
 - [ ] `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`
-- [ ] `AbsoluteArea` uses `renderContext.getSite()` as parent
-- [ ] Structural container nodes use `jmix:hiddenType` (hidden from picker)
 - [ ] Decision made: page template vs sectioning component (see Step 4)
 - [ ] `yarn build && yarn jahia-deploy` run and template appears in Jahia UI
 

package/dist/opencode/.agents/skills/jahia-dev-create-template-set/SKILL.md

@@ -119,66 +119,39 @@ yarn build && yarn jahia-deploy
 
 Verify the module is installed:
 
-```bash
-curl -s -u root:root1234 -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -H "Content-Type: application/json" \
-  -d '{"query":"{ jcr { nodeByPath(path:\"/modules/<module-name>\") { name } } }"}'
+```
+tool: content.get
+args: { "path": "/modules/<module-name>" }
 ```
 
-Replace `<module-name>` with the `name` from `package.json`. The response should contain `"name": "<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 the Provisioning API — **do not use the UI**.
-
-> ⚠️ **CRITICAL: syntax is `- createSite: ""`** — the empty string `""` after the colon is **mandatory**. Without it, Jahia returns HTTP 200 but silently creates nothing. Using `- createSite:` with nested properties is **wrong and will fail silently**.
+After the module is deployed, create the site via MCP:
 
-```bash
-MODULE_NAME=<module-name>   # value of "name" in package.json
-
-curl -u root:root1234 \
-     -X POST \
-     -H "Content-Type: application/yaml" \
-     --data-binary "- createSite: \"\"
-  siteKey: ${MODULE_NAME}
-  title: \"My Site\"
-  defaultLanguage: en
-  serverName: localhost
-  templateSet: ${MODULE_NAME}" \
-     http://localhost:8080/modules/api/provisioning
 ```
-
-Or write the script to a file and POST it:
-
-```bash
-MODULE_NAME=<module-name>
-
-cat > /tmp/create-site.yaml <<EOF
-- createSite: ""
-  siteKey: ${MODULE_NAME}
-  title: "My Site"
-  defaultLanguage: en
-  serverName: localhost
-  templateSet: ${MODULE_NAME}
-EOF
-
-curl -u root:root1234 -X POST -H "Content-Type: application/yaml" \
-  --data-binary @/tmp/create-site.yaml \
-  http://localhost:8080/modules/api/provisioning
+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:
-```bash
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d "{\"query\":\"{ jcr { nodeByPath(path:\\\"/sites/${MODULE_NAME}\\\") { name } } }\"}"
+
+```
+tool: site.list
 ```
 
-The response must contain `"name": "<module-name>"`. If the path returns `null`, the site was not created — check that `templateSet` exactly matches the deployed module name.
+The site key must appear in the response. If it does not, check that `templateSet` exactly matches the deployed module name.
 
 ---
 
@@ -229,4 +202,4 @@ If anything goes wrong during setup or scaffolding, refer to the official Jahia
 - [ ] 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 `createSite: ""` — JCR confirms `/sites/<name>` exists
+- [ ] Site created with `site.create` — `site.list` confirms site key exists

package/dist/opencode/.agents/skills/jahia-dev-create-view/SKILL.md

@@ -100,11 +100,11 @@ Every `<img>` must have an `alt` attribute. Decorative images use `alt=""`. Info
 // ❌ Missing alt
 <img src={buildNodeUrl(props.image)} />
 
-// ✅ Descriptive alt from content
-<img src={buildNodeUrl(props.image)} alt={props.imageAlt ?? ""} />
+// ✅ Alt from the image node's title (no extra CND property needed)
+<img src={buildNodeUrl(props.image)} alt={props.image?.getPropertyAsString("jcr:title") ?? ""} />
 ```
 
-Add `- imageAlt (string) i18n` to the CND and `imageAlt?: string` to `types.ts` for any type with an image field.
+The image node already has `jcr:title` (from `mix:title`). **Do not add `imageAlt (string) i18n`** to the CND — it forces editors to enter duplicate data.
 
 ### Colour contrast