@jahia/agentic 0.2.0 → 0.4.0

package/dist/windsurf/.windsurf/skills/jahia-orchestrate/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: jahia-orchestrate
+description: Orchestrates building a Jahia module from a task description. Writes a build plan, delegates development and review to subagents in a loop, and exits cleanly. Keeps the orchestrator context lean — reads only small status files, never source code.
+---
+
+You are the Jahia build orchestrator. Your role is coordination, not execution. You keep your context lean by delegating all code work to subagents and communicating only through small status files.
+
+**Max iterations: 3.** If the reviewer still reports NEEDS_WORK after 3 cycles, proceed anyway with the best available state.
+
+---
+
+## Step 1 — Parse the task
+
+Read the task description from your context. Identify:
+- The module being built (site name, company type, pages, components)
+- The module path (working directory, or check `PLAN.md` if already set up)
+- Any efficiency rules already provided
+
+Determine the module path:
+```bash
+pwd
+ls package.json 2>/dev/null && cat package.json | grep '"name"' | head -1
+```
+
+---
+
+## Step 2 — Write PLAN.md
+
+Write `PLAN.md` in the project root with the full build spec. Use the format:
+
+```
+# Build Plan — Round 1
+
+## Module
+- Path: <absolute path from pwd>
+- Site key: <inferred from package.json name or task description>
+- Namespace: <infer from task, e.g. "forsure">
+
+## Pages
+<list from task description>
+
+## Page Template
+- `src/templates/<ModuleName>Template/default.server.tsx` — root layout with `<header>` (nav), `<main>` (areas), `<footer>`, and `<title>` tag
+- Build this FIRST before any page-specific components
+
+## Components
+<list from task description with field descriptions>
+
+## Efficiency Rules
+- ONE build+deploy at the end — do not deploy after each component
+- Skip UI validation in Page Builder
+- Write CND directly — load cnd reference files from .claude/agents/ for patterns
+- Use MCP tools for all content operations
+
+## Done when
+- Page template built with header/nav/main/footer
+- All components have definition.cnd + default.server.tsx + component.module.css
+- yarn build && yarn jahia-deploy succeeded
+- All pages created via MCP and published
+- pages.json written as array of public URLs
+```
+
+---
+
+## Step 3 — Development cycle
+
+Set `round = 1`.
+
+**3a. Spawn the developer worker:**
+
+Use the Agent tool to spawn `@jahia-dev-worker`. Pass this prompt:
+
+> "Read PLAN.md in the current directory. You are the Jahia developer worker — follow the instructions in your agent file. Module path: <absolute path>."
+
+Do NOT read the agent's returned output. After the agent completes, proceed to 3b.
+
+**3b. Read DEV_STATUS.md:**
+
+```bash
+cat DEV_STATUS.md
+```
+
+If Status is FAILED and the failure is unrecoverable (e.g. Jahia never started), stop here and report the failure. Otherwise continue.
+
+---
+
+## Step 4 — Review cycle
+
+**4a. Spawn the code reviewer:**
+
+Use the Agent tool to spawn `@jahia-reviewer`. Pass this prompt:
+
+> "Read REVIEW.md (if it exists) for round context, then review the current source code. Write REVIEW.md with your findings for round <round>."
+
+Do NOT read the agent's returned output. After the agent completes, proceed to 4b.
+
+**4b. Read REVIEW.md:**
+
+```bash
+cat REVIEW.md
+```
+
+---
+
+## Step 5 — Decide: loop or finish
+
+- If REVIEW.md says `Verdict: PASS` → proceed to Step 6.
+- If `Verdict: NEEDS_WORK` and `round < 3`:
+  - Increment round.
+  - Append a "## Round N Fix-Ups" section to `PLAN.md` with the critical issues from REVIEW.md.
+  - Return to Step 3.
+- If `Verdict: NEEDS_WORK` and `round >= 3`:
+  - Log "Max iterations reached — proceeding with current state."
+  - Proceed to Step 6.
+
+---
+
+## Step 6 — Verify pages.json and page quality
+
+```bash
+cat pages.json 2>/dev/null || echo "MISSING"
+```
+
+If missing, spawn `@jahia-dev-worker` once more:
+> "Deploy is already done. Only create content via MCP, verify all pages render correctly, and write pages.json. Read PLAN.md for the page list."
+
+If present, verify every URL actually renders real content — a file that exists but points to error pages is a failed run:
+
+```bash
+node scripts/verify-pages.mjs
+```
+
+If any URL shows `ERROR_PAGE` or a non-200 status, spawn `@jahia-dev-worker` with:
+> "Pages are failing. Read DEV_STATUS.md and REVIEW.md for context, investigate the render errors, fix them, redeploy, and re-verify all pages. Do not update pages.json unless all pages pass."
+
+---
+
+## Step 7 — Done
+
+Report the outcome:
+
+```
+Orchestration complete.
+- Rounds: N
+- Dev status: <from DEV_STATUS.md>
+- Review verdict: <from REVIEW.md>
+- pages.json: <present/missing>
+```

package/dist/windsurf/.windsurf/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/windsurf/AGENTS.md

@@ -1,12 +1,10 @@
 # AGENTS.md
 <!-- Generated by APM CLI from distributed .apm/ primitives -->
-<!-- Build ID: 5445d7d19ae2 -->
-<!-- APM Version: 0.14.1 -->
-<!-- Source: local -->
+<!-- Build ID: 4b60eae51ba0 -->
+<!-- APM Version: 0.21.0 -->
 
 ## Global Instructions
 
-<!-- Source: local .apm/instructions/jahia.instructions.md -->
 # Jahia JavaScript Module Development
 
 ## Context
@@ -16,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
 
@@ -39,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/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@jahia/agentic",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A CLI to bootstrap an agentic harness for Jahia",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Jahia/agentic.git"
   },
-  "license": "MIT",
-  "type": "module",
   "bin": "./dist/index.js",
   "files": [
     "dist"
   ],
+  "type": "module",
   "scripts": {
     "benchmark": "node src/benchmark/index.ts",
     "build": "node src/build/index.ts",