feat: JS server extension points, client-callable actions, and the JSServerExtensionInvoker SDK

.chachalog/js-server-extension-points.md

@@ -0,0 +1,8 @@
+---
+# Allowed version bumps: patch, minor, major
+javascript-modules: minor
+---
+
+JavaScript modules can now declare choicelist initializers, server-side node validators and actions — extension points that previously required a Java module. Use the new `registerChoiceListInitializer`, `registerNodeValidator`, `registerAction` and `registerRenderFilter` functions from `@jahia/javascript-modules-library`.
+
+Note for existing modules using `server.registry.add("render-filter", …)`: a declared `priority` is now honored (it was previously ignored and forced to 0), which may reorder such filters in the render chain.

docs/2-guides/4-actions/README.md

@@ -0,0 +1,82 @@
+---
+page:
+  $path: /sites/academy/home/documentation/jahia/8_2/developer/javascript-module-development/actions
+  jcr:title: Declaring Actions
+  j:templateName: documentation
+content:
+  $subpath: document-area/content
+---
+
+Actions are HTTP endpoints bound to content nodes: appending `.<actionName>.do` to a node URL invokes the action against that node. They are the classic Jahia mechanism for form submissions and lightweight server endpoints. With JavaScript modules you can declare actions in JavaScript, without writing a Java module.
+
+## Declaring an action
+
+Call `registerAction` at the top level of a server file (it registers the action as a side effect at module startup, like `jahiaComponent`):
+
+```ts
+import { registerAction } from "@jahia/javascript-modules-library";
+
+registerAction(
+  { name: "myModuleGreet", requiredMethods: ["GET"], requireAuthenticatedUser: false },
+  ({ parameters, resource }) => ({
+    json: {
+      greeting: `Hello ${parameters.who?.[0] ?? "world"}`,
+      path: resource.getNode().getPath(),
+    },
+  }),
+);
+```
+
+The action is then reachable on any node URL:
+
+```
+GET /cms/render/live/en/sites/mysite/home.myModuleGreet.do?who=Jahia
+Accept: application/json
+→ 200 {"greeting": "Hello Jahia", "path": "/sites/mysite/home"}
+```
+
+Note that Jahia's render servlet only writes the JSON body when the request declares it accepts JSON — send an `Accept: application/json` header (browsers submitting forms get the redirect/status behavior instead).
+
+## Declaration options
+
+| Option | Description |
+|--------|-------------|
+| `name` | The URL-visible action name. Names are platform-wide (shared with Java modules, last registration wins) — prefix them with your module name. |
+| `requiredMethods` | Allowed HTTP methods, e.g. `["POST"]`. Defaults to Jahia's default (GET and POST). |
+| `requireAuthenticatedUser` | Defaults to **`true`** (Jahia's default): guests get a 401. Set to `false` explicitly for public actions. |
+| `requiredPermission` | Permission required on the target node, e.g. `"jcr:write"`. |
+| `requiredWorkspace` | Restrict to `"default"` or `"live"`. |
+
+## The handler
+
+The handler receives a context object:
+
+- `parameters` — merged query-string and form parameters, as `Record<string, string[]>`,
+- `resource` / `renderContext` / `session` — the target resource, render context and user JCR session,
+- `request` — escape hatch: the raw `HttpServletRequest` (headers, cookies, body),
+- `urlResolver` — escape hatch: the Jahia URL resolver.
+
+And returns (synchronously — no promises):
+
+- `json` — an object serialized as the JSON response body,
+- `statusCode` — HTTP status, default 200,
+- `redirect` (+ `absoluteRedirect`) — redirect the client instead of returning a body.
+
+Returning nothing sends an empty 200.
+
+## CSRF protection for POST actions
+
+POST, PUT and DELETE requests to `.do` URLs are blocked by Jahia's CSRF guard unless the URL is whitelisted. **This is your module's responsibility**: ship an OSGi configuration file in your module's `settings/configurations/` folder:
+
+```properties
+# settings/configurations/org.jahia.modules.jahiacsrfguard-mymodule.cfg
+whitelist = *.myModuleSubmit.do,*.myModuleOther.do
+```
+
+Whitelisting disables CSRF protection for those URLs, so only do it for actions designed to be called without a CSRF token (e.g. public form submissions), and keep the patterns as narrow as possible. Without this file, POST calls to your action fail with a 403.
+
+## Good to know
+
+- **Keep handlers fast and non-blocking** — they run synchronously on a request thread.
+- **Content modifications**: use the provided `session` to read/write JCR content as the calling user; standard permissions apply, plus `requiredPermission` if you set it.
+- **Errors**: an exception thrown by the handler results in an error response; validate input and return explicit `statusCode` values (e.g. 400) for expected failures.

docs/2-guides/5-choicelist-initializers/README.md

@@ -0,0 +1,70 @@
+---
+page:
+  $path: /sites/academy/home/documentation/jahia/8_2/developer/javascript-module-development/choicelist-initializers
+  jcr:title: Declaring Choicelist Initializers
+  j:templateName: documentation
+content:
+  $subpath: document-area/content
+---
+
+Choicelist initializers populate the dropdown lists offered to editors in Content Editor. Out of the box, Jahia provides initializers such as `resourceBundle` or `nodes`; with JavaScript modules you can declare your own initializers in JavaScript, without writing a Java module.
+
+## Declaring an initializer
+
+Call `registerChoiceListInitializer` at the top level of a server file (it registers the initializer as a side effect at module startup, like `jahiaComponent`):
+
+```ts
+import { registerChoiceListInitializer } from "@jahia/javascript-modules-library";
+
+registerChoiceListInitializer({ key: "myModuleColors" }, ({ locale }) => [
+  { label: locale.startsWith("fr") ? "Rouge" : "Red", value: "red" },
+  { label: locale.startsWith("fr") ? "Vert" : "Green", value: "green" },
+]);
+```
+
+Then reference the initializer's key from a property definition in your CND file:
+
+```cnd
+[mymodule:myComponent] > jnt:content, mix:title
+ - color (string, choicelist[myModuleColors])
+```
+
+The callback returns the list of choices as `{ label, value, properties? }` objects:
+
+- `label` is the text shown to the editor,
+- `value` is the string persisted in the JCR,
+- `properties` is optional metadata interpreted by the editing UI, e.g. `{ defaultProperty: true }` to preselect a choice, or `{ image: "/path.png" }` to display a thumbnail.
+
+## The initializer context
+
+The callback receives a context object:
+
+| Property | Description |
+|----------|-------------|
+| `param` | The parameter from the CND declaration: `choicelist[myModuleColors='myParam']` passes `"myParam"`. Empty string when absent. |
+| `locale` | BCP-47 language tag of the content language being edited (e.g. `"en"`, `"fr"`) — not the editor's UI language. Use it to localize labels. |
+| `values` | Choices accumulated by previous initializers when several are chained in the CND declaration (e.g. `choicelist[resourceBundle,myModuleColors]`). Include them in your result to keep them. |
+| `node` | The node being edited, when it exists (it does not on creation forms). |
+| `java` | Escape hatch: the raw Java objects received by the underlying `ModuleChoiceListInitializer` — `propertyDefinition` (`ExtendedPropertyDefinition`), `locale` (`java.util.Locale`), `values`, `context`. |
+
+For example, an initializer that lists values differently per property and honors a parameter:
+
+```ts
+registerChoiceListInitializer({ key: "myModuleSizes" }, ({ param, values, java }) => {
+  const sizes = [
+    ...values,
+    { label: "Small", value: "s" },
+    { label: "Medium", value: "m" },
+  ];
+  if (param === "extended") {
+    sizes.push({ label: `Large (${java.propertyDefinition.getName()})`, value: "l" });
+  }
+  return sizes;
+});
+```
+
+## Good to know
+
+- **Keys are platform-wide.** Initializer keys live in a single namespace shared with Java modules; the last registration wins. Prefix your keys with your module name (`myModuleColors`, not `colors`).
+- **Keep callbacks fast.** The callback runs synchronously every time an editor form displays the choicelist.
+- **Labels are your responsibility.** Unlike `choicelist[resourceBundle]`, labels are not resolved from resource bundles automatically — return localized labels using the `locale` from the context (you can use your module's i18n setup or any custom logic).

docs/2-guides/6-migrations/README.md

@@ -0,0 +1,114 @@
+---
+page:
+  $path: /sites/academy/home/documentation/jahia/8_2/developer/javascript-module-development/migrations
+  jcr:title: Writing Migrations
+  j:templateName: documentation
+content:
+  $subpath: document-area/content
+---
+
+Migrations are run-once TypeScript scripts shipped with your module, executed when a new version of the module starts. They reconcile existing content with changes in your content type definitions — the JavaScript equivalent of Jahia's Groovy `META-INF/patches` scripts, with a typed API and built-in guard rails.
+
+Typical uses: removing leftover values of a dropped property, backfilling a default on existing content, converting values after a property type change, deleting a retired node type, or renaming a node type and rebinding its content.
+
+## Declaring a migration
+
+Call `registerMigration` at the top level of a server file (it registers the migration as a side effect at module startup, like `registerAction`). Convention: one migration per file under `src/migrations/`:
+
+```ts
+// src/migrations/2.0.0-01-remove-legacy-color.server.ts
+import { registerMigration } from "@jahia/javascript-modules-library";
+
+registerMigration(
+  {
+    name: "2.0.0-01-remove-legacy-color",
+    description: "color was dropped from mymodule:banner in 2.0.0 — clean leftover values",
+  },
+  ({ migrate }) => {
+    migrate.removePropertyValues({ nodeType: "mymodule:banner", property: "color" });
+  },
+);
+```
+
+The `name` is the migration's **run-once identity and ordering key**:
+
+- A module's migrations run in lexicographic order of their names. Use the `"<moduleVersion>-<NN>-<slug>"` convention to keep them sorted.
+- Execution is recorded under the name in Jahia's module patch status store (`/module-management` → `j:bundlesScripts`, shared with Groovy patches). Whatever the outcome, a recorded migration **never runs again** — never rename or reorder a released migration; ship a new one instead.
+
+Migrations run **synchronously** on the module start thread (like actions, they must not be `async`), on the **processing server only**, and by the time they run the module's new definitions are already registered.
+
+## The `migrate.*` helpers
+
+Every helper iterates both the `default` and `live` workspaces (override with `workspaces`), commits in batches (`batchSize`, default 100), handles internationalized properties on their translation subnodes, logs progress, and no-ops gracefully when the node type was never registered on this instance (fresh installs).
+
+```ts
+// U1 — remove a property + clean its values
+migrate.removePropertyValues({ nodeType: "mymodule:banner", property: "color" });
+
+// U2 — add a property + backfill existing content
+migrate.setPropertyValues({
+  nodeType: "mymodule:banner",
+  property: "theme",
+  onlyIfMissing: true, // default — never clobbers an existing value
+  value: (node) => (node.getProperty("price").getDouble() > 1000 ? "premium" : "light"),
+});
+
+// U3 — change a property's data type + convert values
+migrate.convertPropertyValues({
+  nodeType: "mymodule:banner",
+  property: "priority",
+  convert: (value) => Number.parseInt(value.getString(), 10), // undefined = leave untouched
+});
+
+// U4 — delete a definition (owned by this module)
+migrate.removeNodeType({
+  nodeType: "mymodule:legacyBanner",
+  ifContentExists: "delete", // default is "fail" — destroying content is opt-in
+});
+
+// U5 — rename a definition + rebind existing items
+migrate.changeNodeType({
+  from: "mymodule:oldBanner",
+  to: "mymodule:banner", // must exist in the module's current definitions
+  mapProperties: { legacyTitle: "title" },
+});
+```
+
+Selection options on the bulk helpers: `scope` (limit to a subtree), `where` (a JCR-SQL2 constraint fragment), `includeSubtypes` (default `true`). Definition operations (`removeNodeType`, `changeNodeType`) only accept node types **owned by your module** — cross-module definition surgery is not supported.
+
+## The imperative escape hatch
+
+For everything else (ACL fixes, node moves, one-off repairs), open a system session or use the batching engine directly:
+
+```ts
+registerMigration({ name: "2.0.0-02-fix-root-title" }, ({ jcr, log, skip }) => {
+  jcr.withSystemSession({ workspace: "default" }, (session) => {
+    const path = "/sites/mysite/contents/catalog-root";
+    if (!session.nodeExists(path)) skip("nothing to fix on this instance");
+    session.getNode(path).getRealNode().setProperty("jcr:title", null);
+    session.save();
+    log.info(`Cleaned stray jcr:title on ${path}`);
+  });
+
+  jcr.forEachNode(
+    { query: "SELECT * FROM [mymodule:banner]", workspaces: ["default", "live"] },
+    (node) => node.setProperty("migrated", true),
+  );
+});
+```
+
+With `locale: null` (the default), system sessions see translation subnodes as plain nodes — usually what migrations want.
+
+## Outcomes and failure semantics
+
+- Returning normally records `.installed`.
+- Calling `context.skip(reason)` records `.skipped`.
+- Throwing records `.failed`, and the module's **remaining migrations are held back** — persistently, across restarts and redeploys — until the failed record is cleared and the migration succeeds. The module itself still starts — migration failures never break startup.
+
+All three outcomes are terminal. Batches already committed before a failure stay committed (JCR has no cross-save transactions), so write migrations to be **idempotent** — the built-in helpers are idempotent by construction.
+
+## Development and testing
+
+- `migrations.autoRun` (configuration PID `org.jahia.modules.javascript.modules.engine.migrations`, default `true`): set to `false` on development servers to log pending migrations at module start instead of running them.
+- The reliable test is an end-to-end one against a real Jahia: provision the previous module version, create content, deploy the new version, and assert the transformed content — see `tests/cypress/e2e/engine/migrationTest.cy.ts` in the javascript-modules repository for a complete example (statuses, all five operations, skip/failure semantics).
+- To re-run a migration on a development instance, remove its entry from the `j:bundlesScripts` property of `/module-management` (e.g. in the JCR browser) and restart the module. Dedicated CLI/GraphQL tooling for status, dry runs, and resets is planned.

docs/3-reference/1-cnd-format/README.md

@@ -124,6 +124,8 @@ Speaking of the UI, let's list all possible visual editor hints for string prope
 
 This hint will display a dropdown list in the UI. The list of choices is defined in the constraints, as a list of strings.
 
+You can also populate the dropdown from JavaScript by declaring your own initializer key with `registerChoiceListInitializer` and referencing it as `choicelist[myKey]` — see the [choicelist initializers guide](../../2-guides/5-choicelist-initializers/README.md).
+
 #### `choicelist[componentTypes='<types>']`
 
 The dropdown list will be populated with a list of coma-separated component types or mixins.

docs/3-reference/3-node-validators/README.md

@@ -0,0 +1,61 @@
+---
+page:
+  $path: /sites/academy/home/documentation/jahia/8_2/developer/javascript-module-development/node-validators
+  jcr:title: Server-Side Node Validators
+  j:templateName: documentation
+content:
+  $subpath: document-area/content
+---
+
+Node validators run on the server every time a JCR session saves a node of a given type. Returning violations rejects the save and surfaces error messages in Content Editor — attached to a specific field or to the whole node. With JavaScript modules you can declare validators in JavaScript, without writing a Java module.
+
+## Declaring a validator
+
+Call `registerNodeValidator` at the top level of a server file (it registers the validator as a side effect at module startup, like `jahiaComponent`):
+
+```ts
+import { registerNodeValidator } from "@jahia/javascript-modules-library";
+
+registerNodeValidator({ nodeType: "mymodule:article" }, (node) => {
+  const email = node.getPropertyAsString("email");
+  if (email && !email.includes("@")) {
+    return { message: "Please provide a valid email address", propertyName: "email" };
+  }
+});
+```
+
+The callback receives the `JCRNodeWrapper` being saved and returns:
+
+- **nothing** — the node is valid,
+- **one violation** or **an array of violations** — the save is rejected.
+
+A violation is `{ message, propertyName? }`: with `propertyName`, the message is shown on that field in Content Editor; without it, it is shown as a node-level error.
+
+## Declaration options
+
+| Option | Description |
+|--------|-------------|
+| `nodeType` | Node type (primary or mixin) the validator applies to, matched with `isNodeType()`. |
+| `name` | Distinguishes several validators on the same node type in one module. Default `"default"`. |
+| `skipOnImport` | Skip this validator during content imports. Default `false`. |
+| `advanced` | Run in the advanced phase, which only runs once **all** default-phase validators passed. Default `false`. |
+
+The two phases mirror Jahia's Java validator groups: default-phase violations suppress the advanced phase entirely (advanced checks can assume basic integrity).
+
+## Localizing messages
+
+Messages of the form `{my.bundle.key}` (the whole message being a single `{…}` reference) are resolved by Jahia against the deployed resource bundles, in the editor's UI locale — the same mechanism Java validators use. Ship the keys in your module's `settings/resources/*.properties` bundles:
+
+```ts
+return { message: "{mymodule.validation.email.invalid}", propertyName: "email" };
+```
+
+Any other message is displayed verbatim. Alternatively, resolve the text yourself in the callback using `context.locale` (the saving session's locale as a BCP-47 tag, possibly null).
+
+## Good to know
+
+- **Never call `session.save()` inside a validator** — it would recurse into validation.
+- **Keep validators fast**: they run synchronously on every matching session save (editing, APIs, publication-driven saves).
+- **i18n properties**: Jahia silently drops violations attached to internationalized properties when the saving session has no locale; return a node-level violation as a fallback if that matters for your check.
+- **Failure policy**: a validator that throws fails the save with a generic node-level message (fail closed) and logs the error with the validator key; a returned violation without a string `message` is logged and ignored.
+- **GraphQL/API saves** are validated too — the violation messages appear in the mutation errors.