@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/reference/print-template-definition.md

@@ -0,0 +1,22 @@
+---
+title: print-template-definition schema
+audience: tenant
+generated: true
+---
+
+# `print-template-definition` schema
+
+Print Template Designer's content model (@erp/print-engine) — Report's band/element sibling with a physical mm page + merge-tag text. Dashboards have NO separate schema — use `page`.
+
+Pull the full JSON Schema: `erp schema pull print-template-definition`  ·  MCP: `erp_get_schema {"name":"print-template-definition"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `name` | string | yes |  |
+| `description` | string |  |  |
+| `metadata` | object |  |  |
+| `modules` | array |  |  |
+| `definition` | object | yes |  |
+

package/bundle/docs/reference/provider-definition.md

@@ -0,0 +1,22 @@
+---
+title: provider-definition schema
+audience: tenant
+generated: true
+---
+
+# `provider-definition` schema
+
+Provider Designer's content model (ProviderAuthoringController) — kind/connectionRef/basePath/supports.
+
+Pull the full JSON Schema: `erp schema pull provider-definition`  ·  MCP: `erp_get_schema {"name":"provider-definition"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `name` | string | yes |  |
+| `description` | string |  |  |
+| `metadata` | object |  |  |
+| `modules` | array |  |  |
+| `definition` | object | yes |  |
+

package/bundle/docs/reference/report-definition.md

@@ -0,0 +1,22 @@
+---
+title: report-definition schema
+audience: tenant
+generated: true
+---
+
+# `report-definition` schema
+
+Report Designer's content model (@erp/report-engine) — band/element grid.
+
+Pull the full JSON Schema: `erp schema pull report-definition`  ·  MCP: `erp_get_schema {"name":"report-definition"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `name` | string | yes |  |
+| `description` | string |  |  |
+| `metadata` | object |  |  |
+| `modules` | array |  |  |
+| `definition` | object | yes |  |
+

package/bundle/docs/reference/rule.md

@@ -0,0 +1,30 @@
+---
+title: rule schema
+audience: tenant
+generated: true
+---
+
+# `rule` schema
+
+Frontend rule-engine definition (page-level conditional visibility/computed-value rules).
+
+Pull the full JSON Schema: `erp schema pull rule`  ·  MCP: `erp_get_schema {"name":"rule"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `id` | string | yes |  |
+| `name` | string | yes | Stable marketplace-facing name (Phase 21 §4c). |
+| `description` | string |  |  |
+| `event` | string | yes | Dotted event-name pattern: '*' matches one segment, trailing '**' matches any remainder. |
+| `priority` | integer | yes | One of the band values 1/5/10/100 unless priorityOverride is true. Bands confer timing and veto rights (ADR 0008 §4): security(1) and validation(5) run synchronously pre-commit and can veto; business(10) sync; notification(100) async post-commit. |
+| `priorityOverride` | boolean |  | Explicit opt-out of the band constraint. Deliberate, visible, audited. |
+| `enabled` | boolean |  |  |
+| `scope` | object |  | Match dimensions beyond event name and tenant. Unset means any. |
+| `watchedFields` | array |  | Fire only when one of these data fields changed between data.old and data.new (ADR 0008 §2). Fires when old/new are absent (creation). |
+| `condition` | string |  | Phase 1 expression over ${event.*} plus the ambient scopes. Boolean true fires; false/Null skips; non-Boolean/unresolvable is a distinct observable skip. |
+| `suppressSelfTrigger` | boolean |  | Don't re-fire from events this rule's own actions caused (ADR 0008 §5). |
+| `actions` | array | yes | Phase 2 action chain(s), executed by the Action Engine with its frozen retry/timeout/error semantics. |
+| `metadata` | object |  | Marketplace-publishable shape (Phase 21 §4c): version required at publish time. |
+

package/bundle/docs/reference/workflow-definition.md

@@ -0,0 +1,28 @@
+---
+title: workflow-definition schema
+audience: tenant
+generated: true
+---
+
+# `workflow-definition` schema
+
+A real multi-stage approval workflow (engine-workflow) — stagesJson/tasksJson/transitionsJson (each itself a JSON-encoded string) + a top-level approvalPermissions array.
+
+Pull the full JSON Schema: `erp schema pull workflow-definition`  ·  MCP: `erp_get_schema {"name":"workflow-definition"}`
+
+## Top-level properties
+
+| Property | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `name` | string | yes | Unique per tenant; a domain module's REST layer starts instances by this exact name, e.g. "employee.transfer". |
+| `description` | string |  |  |
+| `stagesJson` | string | yes |  |
+| `tasksJson` | string | yes |  |
+| `transitionsJson` | string | yes |  |
+| `approversJson` | string |  |  |
+| `slasJson` | string |  |  |
+| `escalationsJson` | string |  |  |
+| `notificationsJson` | string |  |  |
+| `metadataJson` | string |  |  |
+| `approvalPermissions` | array |  | Which role (by its stable role.code, never a mutable display name) may decide which named approvalObject task. |
+

package/bundle/docs/troubleshooting/grid-shows-zero-rows.md

@@ -0,0 +1,82 @@
+---
+title: "\"My grid shows 0 rows\""
+audience: tenant
+---
+
+# "My grid shows 0 rows"
+
+A `core.grid` renders empty and there is **no error message**. Work through this
+in order.
+
+## 1. Is `metadata.dataSource` set, and on the page?
+
+Open the page file. The **top level** (sibling of `definition`, not inside it,
+not on any block) must have:
+
+```json
+"metadata": { "dataSource": "oeq-equipment-provider" }
+```
+
+`core.grid` has no data property. If `dataSource` is missing, on the grid block,
+or inside `definition`, the grid gets nothing.
+
+## 2. Does the string match a provider `name` exactly?
+
+There must be a file `spk-assembly/metadata/provider/*.json` whose `name` field
+is **character-for-character** equal to the `dataSource` string. Check for a
+typo, a plural, a stray dash.
+
+```bash
+erp plugin test spk-assembly
+```
+
+catches this as **PAGE-DS-001** and prints the mismatched name.
+
+## 3. Does the provider's `basePath` actually return rows?
+
+For an entity you own it should be `/api/v1/entities/<entityName>/records`. Test
+it directly:
+
+```bash
+erp api get "/api/v1/entities/oeq_equipment/records/query?size=5"
+```
+
+- Rows come back → the provider path is fine; the problem is wiring (steps 1–2)
+  or filtering (step 4).
+- `{ "rows": [], "total": 0 }` → the table genuinely has no rows. Create one and
+  retry.
+- 404 → wrong `basePath`.
+
+## 4. Is an `externalFilter` hiding everything?
+
+If the grid binds `externalFilter` to a page object, check what's in that object
+on mount. A stale `status: ""` or an un-cleared search string can filter out
+every row. In the mount loader, initialise the filter object to `{}` or omit
+problematic keys.
+
+## 5. Is `refreshTrigger` stuck?
+
+If the grid only ever loads with the filter/refresh value it had at mount, make
+sure `refreshTrigger` binds a page value that actually changes (you toggle
+`page.gridRefreshTick` after writes), and that the mount loader sets it to a
+defined initial value (`0`).
+
+## 6. Row-level permissions
+
+If the grid is empty **only for some users**, that's row-level security doing its
+job. Check the user's role and the entity's permission keys.
+
+## The fast check
+
+```bash
+# does the raw endpoint the provider points at return data?
+erp api get "/api/v1/entities/<entity>/records/query?size=5"
+```
+
+Whatever that returns is what a correctly-wired grid shows. If it has rows and
+the grid doesn't, the bug is in steps 1–5.
+
+## See also
+
+- [Wire a page's data](../guides/wire-a-pages-data.md)
+- [How does a page get its data?](../concepts/page-data-flow.md)

package/bundle/docs/troubleshooting/job-never-runs.md

@@ -0,0 +1,89 @@
+---
+title: "\"My scheduled job never runs\""
+audience: tenant
+---
+
+# "My scheduled job never runs"
+
+You seeded a job config row but nothing happens. Work through this in order.
+
+## 1. Is the job registered for your tenant?
+
+```bash
+erp api get "/api/v1/jobs/engine-entity.status-date-sweep"
+```
+
+- `{ "status": "ENABLED", ... }` → registered. Go to step 2.
+- 404 → **not registered.** The job registers on the **first** config row via an
+  `AFTER_CREATE` register rule. Either:
+  - your plugin seeded no config row (check the install log for
+    `PluginDataSeedInstaller: ... -> entity entity_<x>_config`), or
+  - for the aggregation / cadence / compliance / cross-plugin / document jobs you
+    **must ship the register rule yourself** —
+    `metadata/rules/ensure_<job>_registered.json` with an unconditional
+    `AFTER_CREATE` `EXECUTE_SERVICE`. Only the **status-date-sweep** job's
+    register rule ships with the platform.
+
+## 2. Run it on demand and read the result
+
+```bash
+erp api post "/api/v1/jobs/engine-entity.status-date-sweep/execute" --body "{}"
+# → { "executionId": 534 }
+
+erp api get "/api/v1/jobs/engine-entity.status-date-sweep/executions?size=1"
+```
+
+The latest execution's `resultJson`:
+
+```json
+{ "swept": 0, "failed": 0, "rowsScanned": 92, "configsScanned": 28 }
+```
+
+- **`configsScanned: 0`** → the job sees no config rows. Your seed didn't land,
+  or `active` is `false` on the rows.
+- **`configsScanned` > 0 but `swept: 0`** → configs are seen but no record
+  matched. Go to step 3.
+- **`failed` > 0** → a matching record's update threw. Go to step 4.
+
+## 3. `swept: 0` — why does no record match?
+
+For each config row, a record is swept only if **all** of:
+
+- its `status_field` value is **exactly** one of `when_status_in` (case
+  matters — match the enum);
+- its `date_field` satisfies `compare_op` against `now` (± `day_offset` days);
+- (aggregation/compliance) it passes any `when_status_in` filter.
+
+Common causes:
+
+- `when_status_in: "checked_out"` but the enum value is `CHECKED_OUT`.
+- `day_offset` omitted, so "within 3 days" is really "on the exact day".
+- `date_field` is null on the records (a null date never satisfies a comparison).
+
+Set up a record that should obviously match and re-run.
+
+## 4. `failed` > 0 — the update threw
+
+```bash
+erp logs tail --lines 200 --grep "status/date sweep: failed to update"
+```
+
+```
+Entity status/date sweep: failed to update oeq_checkout #1 (tenantId=2):
+  PreparedStatementCallback; bad SQL grammar [update oeq_checkout set return_due_soon = ? ...]
+```
+
+The most common cause: the config's `set_field` is a **boolean** column and the
+job writes the value as a string. **Fix:** flip a status enum value
+(`DUE_SOON`, `OVERDUE`) instead of a boolean flag.
+
+## 5. It works on demand but not on schedule
+
+The cron is `0 5 0 * * *` (00:05 daily, per tenant). It won't fire mid-day.
+Test with `/execute`; trust the schedule once `/execute` is clean.
+
+## See also
+
+- [Add a scheduled reminder job](../guides/add-a-reminder-job.md)
+- [Seed config and reference data on install](../guides/seed-data-on-install.md)
+- Tutorial chapter 7: [the return-due reminder job](../tutorial/07-return-due-reminder-job.md)

package/bundle/docs/troubleshooting/known-gotchas.md

@@ -0,0 +1,193 @@
+---
+title: Known gotchas
+audience: tenant
+---
+
+# Known gotchas
+
+The mistakes everyone makes once. Each entry: **symptom → cause → fix.** All real,
+found in a live build (many while building the [tutorial module](../tutorial/index.md)).
+
+## Entities
+
+### `label` fails the install with `invalid input syntax for type json`
+
+**Cause:** an entity's `label` or a field's `label` was a bare string.
+**Fix:** the column is JSON, so the *string* must be valid JSON. Entity:
+`"label": "{\"en\":\"Equipment\"}"`. Field: `"label": "\"Asset Tag\""`. Same for
+`typeParams` (`"{\"enumValues\":[...]}"`) and a workflow's
+`stagesJson`/`tasksJson`/`transitionsJson`.
+
+### A field is silently missing after install
+
+**Cause:** `required: false` without `nullable: true` (or vice-versa) on a table
+that already has rows — the `ALTER TABLE ADD COLUMN ... NOT NULL` fails but the
+metadata row was inserted.
+**Fix:** always pair them. `required:true` ⇒ `nullable:false`;
+`required:false` ⇒ `nullable:true`. Then bump the version and re-publish.
+
+### A big blob of text is rejected / truncated
+
+**Cause:** `dataType: "long"` — that's the 64-bit **integer** type.
+**Fix:** use `dataType: "text"`.
+
+### The generic status-date-sweep job reports `"failed": N` on your rows
+
+**Fixed 2026-09-10:** a sweep config whose `set_field` (or `status_field`) is a
+**boolean**, **integer** or **numeric** column now works — `set_status_to:
+"true"` / `"42"` is coerced to the column's real type before the write (in
+`EntityRecordService`, so every generic sweep job — status-date, compliance,
+cadence, aggregation, cross-plugin — and entity-rule `SET_VALUE` benefits). An
+unparseable value (e.g. `"maybe"` into a boolean) still counts that one row as
+`failed` without throwing. If you still see `failed: N`, the value genuinely
+doesn't parse for the column type, or the row hit an entity-rule rejection —
+check `erp logs tail`.
+
+## Pages and action chains
+
+### `committed` payload key is `event.new`
+
+**Cause:** a handler read `event.value` / `event.record`.
+**Fix:** the value the user entered or picked is `${event.new}`. For a
+`core.lookup` it's the picked record's **id**.
+
+### `metadata.dataSource` is page-level, not grid-level
+
+**Cause:** put `dataSource` / `entity` / `recordType` on the `core.grid` block —
+it has none of those properties.
+**Fix:** the page artifact's top-level `metadata.dataSource` must equal a
+`metadata/provider/*.json` file's `name`, exactly. Miss or mistype it and the
+grid renders 0 rows with no error. `erp plugin test` catches this as
+**PAGE-DS-001**.
+
+### KPI card shows `undefined`
+
+**Cause:** bound `${out.value}` against a `composite` Data Service.
+**Fix:** `count` → `${out.value}`; `composite` → `${out.results.<step>.value}`.
+`.total` is the unrelated list-pagination envelope.
+
+### A parameterized Data Service `/execute` returns 400
+
+**Cause:** arguments passed as `{ "params": { "search": "x" } }`.
+**Fix:** nest one level deeper: `{ "params": { "parameters": { "search": "x" } } }`.
+A `core.lookup` does this for you.
+
+### `!= null` in an action-engine condition never matches
+
+**Cause:** action-engine quirk.
+**Fix:** use the `isNotNull` / `isNull` operators (rule engine: `is_not_null` /
+`is_null`).
+
+### UI shows a raw i18n key like `office-equipment.x.y`
+
+**Cause:** the key has no entry in `metadata/i18n/en.json`.
+**Fix:** add it. `erp plugin test` lists missing keys as **I18N-001**.
+
+## Rules and workflows
+
+### A workflow-trigger rule fires on every save, not just the transition
+
+**Cause:** the condition checks only `status == PENDING_APPROVAL`.
+**Fix:** add `{ "field": "status__previous", "op": "neq", "value": "PENDING_APPROVAL" }`
+inside an `all` clause.
+
+### Nobody can approve a workflow task
+
+**Cause:** `approvalPermissions` references a role **display name**.
+**Fix:** use `roleCode` — the stable `code`, never the mutable name.
+
+### Install rejects a workflow file
+
+**Cause:** `stagesJson` / `tasksJson` / `transitionsJson` authored as nested
+objects.
+**Fix:** each is a JSON-**encoded string**.
+
+## Publishing
+
+### A same-version re-publish does nothing
+
+**Cause:** the plugin is already installed at that version — the re-publish is a
+silent no-op.
+**Fix:** bump `plugin.json` `version` before every `build` + `publish`, even if
+you're sure the last publish shipped the fix.
+
+### `Refusing to overwrite immutable artifact`
+
+**Cause:** re-publishing a version whose `.spk` was already stored, with
+different bytes (e.g. after a publish that failed later in the pipeline).
+**Fix:** go to the next version number.
+
+### `There is an already loaded plugin ... with the same id`
+
+**Cause:** you **uninstalled** the plugin and the background unload didn't
+complete (it can stall on a transient DB error), so the old PF4J code is still
+loaded and the next `publish` (install-new path) is refused.
+**Fix:** to iterate, **bump the version and re-publish** — don't uninstall.
+Recovery from a stuck state is a backend restart or publishing under a new
+plugin id.
+
+### `plugin.json is missing mainClass` *(fixed 2026-09-10 — no longer occurs)*
+
+A pure-JSON plugin (only declarative metadata artifacts — entities, pages,
+providers, menus, seed-data, workflows, rules, sweep configs — and zero Java
+classes) now publishes with `"mainClass": null` exactly as `erp plugin create`
+scaffolds it. The platform loads it through a built-in generic no-op PF4J entry
+point (`JsonOnlyPlugin`); full lifecycle (start/stop/enable/disable/upgrade),
+artifact installation, migrations and data seeding all run normally. **You do
+not compile or ship any jar.** Only declare a `mainClass` (with a jar in
+`spk-assembly/lib/`) if your plugin genuinely ships Java extensions.
+
+### `A role named "X" already exists` / `Role "X" ... already exists owned by "Y"`
+
+**Cause:** a `plugin.json` role whose `name` or `code` collides with another
+installed plugin's role.
+**Fix:** prefix your role names and codes.
+
+## Runtime / navigation
+
+### The browser URL is not `route.pattern`
+
+**Cause:** treating the menu/page `route.pattern` string as the reachable URL.
+**Fix:** the URL is `/app/<app-slug>/<module-slug>/<pluginId>/<page-name>`. The
+`route.pattern` is an internal routing key.
+
+### A menu item 404s
+
+**Cause:** `navigation.route` doesn't match the page's `route.pattern`.
+**Fix:** copy it exactly.
+
+### A page isn't in the sidenav
+
+**Cause:** the page's `modules` array doesn't name the module it should appear
+under.
+**Fix:** set `modules` to your module's `name`; align the menu file's `modules`
+too.
+
+## Environment / tooling (Windows)
+
+### `erp` command turns `/api/v1/...` into `C:/Program Files/Git/api/v1/...`
+
+**Cause:** Git Bash rewrites a leading `/` in an argument to a Windows path.
+**Fix:** run the command from PowerShell, or set `MSYS_NO_PATHCONV=1`.
+
+### `--tenant 5` errors even though you're logged in
+
+**Cause:** `--tenant` only overrides the `X-Tenant-Id` header; it doesn't
+re-authenticate you.
+**Fix:** your token must already be valid for that tenant.
+
+## Getting unstuck
+
+- `erp logs tail --grep <X-Correlation-Id>` — a failed API response's
+  `X-Correlation-Id` header joins to the exact server-side stack trace. *(SDK
+  connected mode, offline: use the ERP admin log view.)*
+- `erp platform catalog --query "<term>"` — before writing any "there's no X"
+  assumption, check whether the platform already has it.
+- `erp plugin test <dir>` and `node developer-docs/examples/test-examples.mjs` —
+  run both before every publish.
+
+## See also
+
+- [Publishing and install errors](./publishing-errors.md)
+- [My grid shows 0 rows](./grid-shows-zero-rows.md)
+- [My scheduled job never runs](./job-never-runs.md)

package/bundle/docs/troubleshooting/publishing-errors.md

@@ -0,0 +1,119 @@
+---
+title: Publishing and install errors
+audience: tenant
+---
+
+# Publishing and install errors
+
+Every error message `erp plugin publish` can return, what it means, and what to
+do. The install pipeline is all-or-nothing and names the stage it failed at — see
+[How does a plugin get installed?](../concepts/plugin-lifecycle.md).
+
+## Before upload
+
+### `plugin.json is missing mainClass` *(no longer raised, as of 2026-09-10)*
+
+A pure-JSON plugin publishes fine with `"mainClass": null` — the platform loads
+it via a built-in generic entry point, no jar required. Only set `mainClass`
+if your plugin ships its own Java extensions.
+
+### `plugin.json is missing id/version`
+
+Fill them in. `id` is lowercase kebab-case; `version` is semver.
+
+### `could not reach <url>` / `ERR_INVALID_URL`
+
+Wrong env base URL (`erp env list`), the server is down, or — on Git Bash —
+`MSYS_NO_PATHCONV=1` needed.
+
+## Stage VALIDATING
+
+### `Refusing to overwrite immutable artifact at "system/plugins/<id>/<version>/..."`
+
+You already stored a `.spk` under this `<version>`, the new bytes differ, **and
+that version genuinely shipped** (it reached `pf4jState: STARTED` on some
+tenant). A shipped version is write-once — **bump to the next version.**
+
+As of the 2026-09-10 publish-hardening pass this is *no longer* raised for a
+version whose prior install **failed or never started** (a role clash caught
+late, or a metadata-only plugin that isn't PF4J-loaded): re-publishing the same
+version now replaces the stored `.spk` and retries. So the "edit a page,
+re-publish the same version" loop works for JSON-only plugins without a bump.
+You still bump for every change to a version that's live and `STARTED`.
+
+### `one or more page definitions failed block-property validation`
+
+A page sets a property that the block type doesn't have, or uses a block type
+that doesn't exist. Run `erp plugin validate spk-assembly` locally — it reports
+which page and which property. Ground the block first with
+`erp blocks list --type <name>`.
+
+### schema validation failure on an artifact
+
+The named file doesn't match its schema. Run
+`erp schema validate <file> --schema <name>` and
+`node developer-docs/examples/test-examples.mjs`.
+
+## Stage LOADING
+
+### `There is an already loaded plugin ... with the same id (...)`
+
+A previous version of this plugin id is still loaded in PF4J. The platform
+cannot hold two versions of one id at once.
+
+- **Normal upgrade / in-place re-publish**: handled — the publish path now
+  stops + unloads the currently-loaded same-id plugin (with a GC hint) *before*
+  loading the new bundle. `erp plugin publish` / `spark publish` also auto-retry
+  once with a force-unload if they still see this error.
+- **Wedged load** (`state: uninstalled` in `erp plugin list` but `pf4jState:
+  STARTED`): a crash or a transient `Failed to obtain JDBC Connection` during
+  uninstall aborted the unload. Recover without a backend restart:
+
+  ```bash
+  erp plugin force-unload <plugin-id>
+  erp plugin publish <plugin>-<next>.spk --tenant 2
+  ```
+
+  `force-unload` best-effort stops, unloads and GC-hints the stuck classloader,
+  then reports `pf4jState` (`NOT_LOADED` on success). It's idempotent and does
+  not need an active install row. `erp plugin publish --force` runs it for you.
+
+### `plugin manager rejected the package (missing/invalid plugin.json or mainClass?)`
+
+The `lib/*.jar` doesn't contain the class named by `mainClass`, or isn't a valid
+plugin jar. Recompile the stub; confirm
+`jar -tf spk-assembly/lib/*.jar` lists your `.class` file at the right package
+path.
+
+## After code load (rolled back)
+
+### `A role named "X" already exists`
+
+Another installed plugin owns a role with that display **name**. Rename yours.
+
+### `Role "X" (code "Y") already exists owned by "Z"`
+
+Another plugin owns that role **code**. Change your code. (This survives a
+plugin's own uninstall — a role created by `example-plugin` blocks
+`office-equipment` from creating one with the same code.)
+
+### seed-data failure — entity not found
+
+A `metadata/seed-data/*.json` targets an entity your plugin doesn't ship. Ship
+the `metadata/entities/*.json` (or, for a shared config entity, ship the additive
+version of it).
+
+## Verify a successful publish
+
+```bash
+erp plugin list
+```
+
+Your plugin: `"state": "installed"`, `"pf4jState": "STARTED"`,
+`"migrationStatus": "INSTALLED"`. Then hit a page or entity endpoint to confirm
+the new content is live.
+
+## See also
+
+- [How does a plugin get installed?](../concepts/plugin-lifecycle.md)
+- [Publish and upgrade a plugin](../guides/publish-and-upgrade.md)