@jahia/agentic 0.0.0

package/dist/codex/.agents/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/codex/.agents/skills/jahia-dev-start-local/SKILL.md

@@ -0,0 +1,129 @@
+---
+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 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**.
+
+```bash
+MODULE_NAME=<module-name>   # value of "name" in package.json
+
+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
+```
+
+Verify the site exists:
+```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 } } }\"}"
+```
+
+The response must contain `"name": "<module-name>"`. If it returns `null`, the site was not created — 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 Provisioning API (`createSite: ""` with correct templateSet)
+- [ ] GraphQL confirms `/sites/<site-key>` node 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