@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/guides/responsive-plugin.md

@@ -0,0 +1,117 @@
+---
+title: Make a plugin work on desktop, tablet, and mobile
+audience: tenant
+---
+
+# Make a plugin work on desktop, tablet, and mobile
+
+## What you're doing
+
+The platform is **mobile-first**: a page you author with no responsive settings
+renders as a single stacked column and already works on a phone. This guide is
+about the deliberate adjustments — hiding a column on small screens, a
+desktop-only side panel, a device-restricted menu item.
+
+## The default you get for free
+
+- Rows and columns collapse to a single column below the `sm` breakpoint.
+- A `core.grid` becomes horizontally scrollable inside its own container.
+- KPI rows wrap.
+
+So the tutorial pages — header, KPI row, filter row, grid, dialogs — are usable
+on mobile with zero extra work. **Verify that's true before adding overrides.**
+
+## The breakpoint model
+
+- The base breakpoint is **`xs`** (mobile). It has no key inside
+  `breakpointOverrides` — its own hidden state is the sibling property
+  **`hiddenAtXs`** on the row / column / item.
+- Wider breakpoints are **`sm`, `md`, `lg`, `xl`**, set under `breakpoints`:
+
+```json
+{
+  "id": "item-3",
+  "kind": "block",
+  "hiddenAtXs": true,
+  "breakpoints": {
+    "md": { "hidden": false },
+    "lg": { "span": 4 }
+  },
+  "block": { "...": "..." }
+}
+```
+
+Read that as: hidden on mobile, shown again from `md` up, and 4/12 columns wide
+from `lg` up. This is how you express "desktop-only content" — author it hidden
+at `xs`, re-show it at a wider breakpoint.
+
+- **`spanAtXs`** (on a column) is an independent 1–12 width for mobile, not a
+  mirror of `sm`.
+
+## The complete example — a detail panel that's a dialog on mobile, a column on desktop
+
+The tutorial keeps it simple: detail is always a `core.dialog`, which works
+everywhere. If you want a side-by-side layout on desktop, put the detail content
+in a second column that is `hiddenAtXs: true` with `breakpoints.lg.hidden:
+false`, and keep the dialog for `xs`–`md`.
+
+```json
+"rows": [
+  { "id": "row-main", "columns": [
+    { "id": "col-list", "items": [ /* grid */ ], "spanAtXs": 12, "breakpoints": { "lg": { "span": 7 } } },
+    { "id": "col-detail", "hiddenAtXs": true, "breakpoints": { "lg": { "hidden": false, "span": 5 } },
+      "items": [ /* detail card bound to page.detailRecord */ ] }
+  ] }
+]
+```
+
+## Device-restricted menu items
+
+A menu node's `visibility.devices`:
+
+```json
+"visibility": { "visible": true, "enabled": true, "devices": ["desktop", "tablet"] }
+```
+
+`[]` = every device. Use this for a bulk-admin screen you don't want on phones.
+
+## Page variants (advanced)
+
+A page can carry `variants` — alternate layouts selected by role, device class,
+or a route param:
+
+```json
+"variants": [
+  { "id": "mobile", "rule": { "deviceClass": "mobile" }, "rows": [ /* a trimmed layout */ ] }
+]
+```
+
+Use this only when the mobile experience is genuinely a different screen, not
+just a reflow. For most list pages the default stacking plus a couple of
+`hiddenAtXs` flags is enough.
+
+## How to verify it worked
+
+`erp plugin test` validates the breakpoint shape. For the real check, publish and
+open the page in the ERP, then use your browser's device-emulation to switch
+between phone, tablet, and desktop widths. Confirm:
+
+- nothing overflows the viewport horizontally (the page body must never
+  scroll sideways — only inner containers);
+- every action reachable on desktop is reachable on mobile (even if in a
+  different place);
+- text stays legible (no fixed pixel widths forcing tiny text).
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| page scrolls sideways on mobile | a fixed-width block or `minWidth` on a container | use relative units; let the grid scroll inside its own container |
+| `xs` override ignored | put an `xs` key inside `breakpointOverrides` | there is no `xs` key there — use `hiddenAtXs` / `spanAtXs` |
+| desktop-only panel shows on mobile | set `breakpoints.lg.hidden:false` without `hiddenAtXs:true` | you must hide at `xs` first, then re-show |
+| a dialog is unusable on a phone | fixed `minWidth: 520px` on the dialog content | use `max-width: 100%` / flexible widths |
+
+## What to read next
+
+- [Build a page](./build-a-page.md)
+- [Add menus](./add-menus.md)

package/bundle/docs/guides/seed-data-on-install.md

@@ -0,0 +1,127 @@
+---
+title: Seed config and reference data on install
+audience: tenant
+---
+
+# Seed config and reference data on install
+
+## What you're doing
+
+Making data rows travel **with** the `.spk` instead of a manual per-tenant
+`POST`. Two things need seeding:
+
+1. **reference data** you own — equipment categories, status pick-lists, default
+   settings.
+2. **rows in shared platform config tables** — `entity_status_date_sweep_config`,
+   `entity_aggregation_config`, `entity_cadence_config`, etc. — that make your
+   scheduled jobs exist.
+
+One file per data set under `spk-assembly/metadata/seed-data/`. The
+`PluginDataSeedInstaller` upserts them on every install, upgrade, and
+auto-provision — **idempotently**, keyed by the fields you nominate.
+
+## The complete example
+
+`spk-assembly/metadata/seed-data/office-equipment-categories.json` —
+[real file](../tutorial/example-plugin/spk-assembly/metadata/seed-data/office-equipment-categories.json):
+
+```json
+{
+  "entity": "oeq_category",
+  "keyFields": ["category_code"],
+  "source": "office-equipment",
+  "rows": [
+    { "category_code": "LAPTOP",  "category_name": "Laptops",  "description": "Portable computers", "status": "ACTIVE", "seeded_by": "office-equipment" },
+    { "category_code": "MONITOR", "category_name": "Monitors", "description": "External displays",  "status": "ACTIVE", "seeded_by": "office-equipment" },
+    { "category_code": "PHONE",   "category_name": "Phones",   "description": "Mobile handsets",    "status": "ACTIVE", "seeded_by": "office-equipment" },
+    { "category_code": "HEADSET", "category_name": "Headsets", "description": "Audio headsets",     "status": "ACTIVE", "seeded_by": "office-equipment" }
+  ]
+}
+```
+
+## Line by line
+
+- **`entity`** — the target entity `name`. It must already exist — ship it in
+  `metadata/entities/` if your plugin owns it.
+- **`keyFields`** — the natural key. On re-install, a row matching **all**
+  `keyFields` is *updated only if a non-key value changed*, otherwise inserted.
+  Never duplicated. Choose a key that is genuinely unique (`category_code`, not
+  `category_name`).
+- **`source`** — your plugin id. Written into a `seeded_by` field if the entity
+  has one — handy for `WHERE seeded_by = 'office-equipment'` cleanup later.
+- **`rows`** — plain field maps. **No tenant id** — the installer supplies it.
+
+## Idempotency in practice
+
+Publish the plugin, then publish it again with a fifth category added. The
+installer log shows:
+
+```
+PluginDataSeedInstaller: office-equipment-categories.json -> entity oeq_category (tenant 2): 1 created, 0 updated, 4 unchanged
+```
+
+The four existing rows are left alone; only the new one is inserted. Verified
+against the tutorial module — the first install logged `4 created`, and no
+re-run ever duplicates them.
+
+## Seeding shared platform config (the important use)
+
+The job guides ([reminder](./add-a-reminder-job.md),
+[aggregation](./add-an-aggregation-job.md), [cadence](./add-a-cadence-job.md),
+[compliance](./add-a-compliance-job.md)) all seed a row into a shared config
+entity. For those you also ship:
+
+1. **the shared config entity file** (`entity_status_date_sweep_config.json`
+   etc.) so a fresh environment that predates it gains the table. The installer
+   is idempotent-additive: an existing table just gains any missing columns.
+   Ship only the additive fields your rows need — see the tutorial's
+   [`entity_status_date_sweep_config.json`](../tutorial/example-plugin/spk-assembly/metadata/entities/entity_status_date_sweep_config.json).
+2. **an `AFTER_CREATE` register rule** on the config entity, calling
+   `ensure<Job>Registered`, so the first seeded row auto-registers the job. (The
+   status-date-sweep job's register rule ships with the platform; the others you
+   ship yourself — see each job guide.)
+
+## Ground yourself first
+
+```bash
+erp schema pull plugin-seed-data
+erp examples patterns --kind jobs     # "install-lifecycle-data-seeding"
+```
+
+## How to verify it worked
+
+```bash
+erp schema validate spk-assembly/metadata/seed-data/office-equipment-categories.json --schema plugin-seed-data
+```
+
+```
+OK — ... matches schema "plugin-seed-data"
+```
+
+After publishing:
+
+```bash
+erp api get "/api/v1/entities/oeq_category/records/query?size=10"
+```
+
+```json
+{ "rows": [
+  { "id": 1, "category_code": "LAPTOP",  "category_name": "Laptops",  "status": "ACTIVE", "seeded_by": "office-equipment" },
+  { "id": 2, "category_code": "MONITOR", "category_name": "Monitors", "status": "ACTIVE", "seeded_by": "office-equipment" }
+], "total": 4 }
+```
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| re-install duplicates rows | `keyFields` not actually unique | pick a real key |
+| seed fails: entity not found | didn't ship the `metadata/entities/*.json` | ship it |
+| job doesn't register despite seeding | no `AFTER_CREATE` register rule (for aggregation/cadence/compliance) | ship it |
+| a `null` in `keyFields` matches nothing / everything | key field is optional and unset in some rows | keep key fields non-null in every row |
+
+## What to read next
+
+- [Add a scheduled reminder job](./add-a-reminder-job.md)
+- Recipe: [install-lifecycle data seeding](../recipes/install-lifecycle-data-seeding.md)
+- Tutorial chapter 2: [the category entity + seeded data](../tutorial/02-category-entity-and-seed.md)

package/bundle/docs/guides/set-up-the-sdk.md

@@ -0,0 +1,120 @@
+---
+title: Set up the SDK and connect to an environment
+audience: tenant
+---
+
+# Set up the SDK and connect to an environment
+
+## What you're doing
+
+Before you can build anything you need the **plugin SDK** talking to **your ERP**.
+The SDK is two programs:
+
+- **the `erp` CLI** — scaffolds plugins, validates them, and publishes them to your ERP.
+- **the `erp-plugin-language` MCP server** — the thing your AI coding agent (Claude
+  Code, Cursor, Codex) calls to look up schemas, widgets, and worked examples so
+  it doesn't have to guess.
+
+An **environment** (or *env*) is one named ERP you talk to — `dev`, `staging`,
+`prod`. The CLI remembers a base URL and a login token per env in
+`~/.erp/config.json`, so you can switch between them with one command.
+
+You do **not** need access to the ERP's source code. Everything the tools need to
+ground themselves — JSON Schemas, the catalog of platform capabilities, curated
+examples, these docs — ships in an **authoring bundle** that the SDK reads
+offline and can refresh from your ERP.
+
+## The complete sequence
+
+```bash
+# 1. point the CLI at your ERP and give the env a name
+erp env use dev --base-url https://erp.example.com
+
+# 2. log in (opens your browser; RFC 8628 device-authorization grant)
+erp login
+
+# 3. confirm who you are and which tenant you're on
+erp whoami
+
+# 4. pull this env's authoring bundle into ~/.erp/cache/
+erp env sync
+
+# 5. install the MCP server config into the current project folder
+erp mcp install
+```
+
+> Until the SDK is published to npm you run it directly. Everywhere these docs
+> say `erp`, substitute `node <sdk>/tools/erp-cli/erp.mjs`. Set a shell alias:
+> `alias erp='node /path/to/tools/erp-cli/erp.mjs'`.
+
+## Line by line
+
+**`erp env use dev --base-url https://erp.example.com`** creates an env named
+`dev` and makes it current. Run it again with a different name to add another
+env; `erp env list` shows them all with a `*` next to the current one. `erp env
+use staging` (no `--base-url`) just switches to an env you already defined.
+
+**`erp login`** opens your browser, you approve the CLI, and an access token +
+refresh token are written to `~/.erp/config.json` (file mode `0600`). Networked
+commands auto-refresh an expired access token, so you rarely log in again. In CI,
+skip the browser: set `ERP_TOKEN=<access token>` and the CLI uses that instead.
+
+**`erp whoami`** prints the env, base URL, tenant id, your user id, and your
+roles. This is the fastest check that your session is live and pointed where you
+think.
+
+**`erp env sync`** downloads the env's authoring bundle (schemas, the frozen
+capability catalog, blocks, validators, docs, plus the live list of entity and
+theme names in your tenant) into `~/.erp/cache/<env>/`. If your ERP doesn't
+expose the bundle endpoint yet this is a no-op and the SDK falls back to the
+bundle shipped inside the SDK package — you can keep going. Re-run it whenever
+your ERP is upgraded. `erp env sync --check` reports drift without downloading.
+
+**`erp mcp install`** writes a `.mcp.json` in the current directory pointing at
+the `erp-plugin-language` MCP server. Your AI agent picks it up automatically the
+next time it opens this folder.
+
+## How to verify it worked
+
+```bash
+erp whoami
+```
+
+Expected — a JSON blob like this (your values differ):
+
+```json
+{
+  "env": "dev",
+  "baseUrl": "https://erp.example.com",
+  "tenantId": 2,
+  "valid": true,
+  "userId": "you@example.com",
+  "roles": ["HR Administrator", "Studio Staff"]
+}
+```
+
+`"valid": true` means the token is good. Then check the MCP wiring:
+
+```bash
+cat .mcp.json
+```
+
+You should see a server entry named `erp-plugin-language`. Restart your AI agent
+in this folder and ask it to call `erp_list_schemas` — it should return a list
+of schema names, not an error.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `erp whoami` says `"valid": false` | token expired and no refresh token | `erp login` again |
+| `could not reach <url>` | wrong base URL, or `/` mangled by Git Bash on Windows | check `erp env list`; on Git Bash set `MSYS_NO_PATHCONV=1` |
+| `erp env sync` downloads nothing | your ERP has no `/api/v1/dev/bundle` endpoint yet | fine — the SDK's built-in bundle is used |
+| AI agent can't see the `erp_*` tools | `.mcp.json` written in a different folder, or agent not restarted | run `erp mcp install` in your project root, restart the agent |
+| `--tenant 5` "does not re-authenticate you" errors | `--tenant` only overrides the header; your token must already be valid for that tenant | log in as a user who has access to that tenant |
+
+## What to read next
+
+- [Create a plugin from scratch](./create-a-plugin.md)
+- [Use the MCP server with an AI agent](./use-the-mcp-server.md)
+- [The tutorial](../tutorial/index.md) builds a real module end to end.

package/bundle/docs/guides/use-the-mcp-server.md

@@ -0,0 +1,104 @@
+---
+title: Use the MCP server with an AI agent
+audience: tenant
+---
+
+# Use the MCP server with an AI agent
+
+## What you're doing
+
+Letting your AI coding agent (Claude Code, Cursor, Codex) build plugins without
+guessing. The `erp-plugin-language` **MCP server** exposes tools the agent calls
+to fetch the real schemas, the real widget catalog, real worked examples, and to
+validate what it wrote — all grounded in *your* ERP's authoring bundle.
+
+## Setup
+
+```bash
+erp mcp install          # writes .mcp.json in the current folder
+```
+
+Restart your agent in that folder. It now has the `erp_*` tools.
+
+## The tools, and when to reach for each
+
+### Grounding — before writing an artifact
+
+| Tool | Returns | Use when |
+| --- | --- | --- |
+| `erp_list_schemas` | every schema name | "what artifact types exist?" |
+| `erp_get_schema {"name":"entity-definition"}` | one full JSON Schema | before writing any entity / page / provider / rule / workflow / seed file |
+| `erp_list_blocks` / `erp_list_blocks {"type":"core.grid"}` | the widget catalog; one widget's full property + event list | before adding a block to a page |
+| `erp_list_grammar_rules` | the page/action-chain grammar | when an action chain isn't behaving |
+| `erp_platform_catalog` / `erp_platform_describe {"className":"..."}` | the live inventory of platform engines, REST mappings, tables; real method signatures for extension points | before assuming "there's no built-in X" |
+
+### Examples — copy a proven shape
+
+| Tool | Returns |
+| --- | --- |
+| `erp_examples_patterns` | curated **named shapes** (`single-stage-self-decide`, `related-record-lookup-field`, `n-days-before-reminder-sweep`, …), each pointing at a real shipped file |
+| `erp_search_examples {"pattern":"employee-search","kind":"data-service"}` | real shipped metadata files matched by name |
+| `erp_search_docs {"query":"..."}` | these docs + the live engine catalog + Java contracts |
+
+### Validation — after writing
+
+| Tool | Checks |
+| --- | --- |
+| `erp_validate_page` | one page against the contract + live block registry |
+| `erp_validate_plugin_pages` | every page in a plugin dir |
+| `erp_validate_connector_definition` | a connector JSON |
+| `erp_lint_plugin_semantics {"pluginDir":"..."}` | PAGE-DS-001 / DS-001 / I18N-001 / SEED-001 / JOB-001 across the whole plugin |
+| `erp_plugin_scaffold` | a starting skeleton for a plugin or extension point |
+
+### Diagnostics
+
+| Tool | Returns |
+| --- | --- |
+| `erp_tail_logs {"grep":"<X-Correlation-Id>"}` | the server-side stack trace for a failed call (join on the response's `X-Correlation-Id` header) |
+
+## A worked interaction
+
+You: *"Add a category lookup field to the equipment form."*
+
+A well-behaved agent will:
+
+1. `erp_examples_patterns` → finds `related-record-lookup-field`, reads the real
+   `promotions.json` it points at;
+2. `erp_get_schema {"name":"data-service-definition"}` and
+   `erp_search_examples {"pattern":"employee-search","kind":"data-service"}` →
+   learns the `search` + `dataView` recipe;
+3. writes `oeq-category-select-options-view.json`, `oeq-category-search.json`,
+   and the `core.lookup` block;
+4. `erp_validate_plugin_pages` and `erp_lint_plugin_semantics` → confirms clean.
+
+Every step is grounded, nothing is guessed.
+
+## The verification-you-can-run trap
+
+Ask the agent to prove each claim with a command whose output you can see —
+`erp plugin test`, `erp api get ...`, `erp api post .../execute` — not "it should
+work now". If the agent can't show you the output, the step isn't done.
+
+## How to verify the MCP wiring itself
+
+Ask the agent to call `erp_list_schemas`. It should return a list of ~25 schema
+names. If it errors or says the tool doesn't exist:
+
+- `cat .mcp.json` — is there an `erp-plugin-language` entry?
+- did you restart the agent in this folder?
+- run `erp mcp install` again in the project root.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| agent invents block properties | didn't call `erp_list_blocks` for that type | tell it to ground first |
+| agent's page fails install on `metadata.dataSource` | skipped `erp_lint_plugin_semantics` | run it before publish |
+| agent "can't find" a tool | `.mcp.json` in wrong folder / agent not restarted | `erp mcp install` in root, restart |
+| schemas look stale | bundle not synced | `erp env sync` |
+
+## What to read next
+
+- [Set up the SDK](./set-up-the-sdk.md)
+- [Validate and test a plugin](./validate-and-test.md)
+- [Expose a plugin operation as an AI tool](./expose-a-plugin-operation-as-an-ai-tool.md) — the *other* MCP concept: the ERP product's own embedded AI assistant calling your plugin at runtime, not your coding agent while you build

package/bundle/docs/guides/validate-and-test.md

@@ -0,0 +1,119 @@
+---
+title: Validate and test a plugin
+audience: tenant
+---
+
+# Validate and test a plugin
+
+## What you're doing
+
+Catching mistakes before you publish. The SDK runs the **same checks the
+platform runs at install time**, so a clean local run means a clean install.
+Three commands, cheapest first.
+
+## The complete sequence
+
+```bash
+erp schema validate spk-assembly/metadata/entities/oeq_equipment.json --schema entity-definition
+erp plugin validate spk-assembly
+erp plugin test    spk-assembly
+```
+
+Plus, over MCP, the semantic linter directly:
+
+```
+erp_lint_plugin_semantics {"pluginDir": "developer-docs/tutorial/example-plugin/spk-assembly"}
+```
+
+## Line by line
+
+### `erp schema validate <file> --schema <name>`
+
+Checks **one** JSON file against **one** schema. Use it while authoring a single
+artifact. Fast, no backend needed.
+
+```
+OK — spk-assembly/metadata/entities/oeq_equipment.json matches schema "entity-definition"
+```
+
+### `erp plugin validate <dir>`
+
+Validates every **page** in the plugin against the page contract *and* the live
+block registry (does each `blockType` exist, does each property it sets actually
+belong to that block).
+
+```
+validated 3 page(s) — clean
+```
+
+### `erp plugin test <dir>`
+
+Runs `plugin validate` **plus** the semantic lints — the checks that catch the
+"looks fine, silently broken" class of bug:
+
+```
+Plugin Tests
+────────────────────────────────────────
+✓ page:equipment-catalog.json
+✓ page:equipment-checkout.json
+✓ page:equipment-register.json
+✓ plugin.json:valid-json
+1 passed, 0 failed, 0 semantic warning(s), 3 skipped
+```
+
+## The semantic lint codes — what each one catches
+
+| Code | Catches | Fix |
+| --- | --- | --- |
+| **PAGE-DS-001** | a page has a `core.grid` but `metadata.dataSource` is missing or doesn't match any `metadata/provider/*.json` `name` — the "0 rows, no error" bug | see [Wire a page's data](./wire-a-pages-data.md) |
+| **DS-001** | a Data Service `filter` compares a value of the wrong type (e.g. a string against a numeric column) | fix the filter, or set `valueType` |
+| **I18N-001** | a page references an i18n key with no entry in `metadata/i18n/en.json` (or a placeholder value) | add the key — see [Add i18n](./add-i18n.md) |
+| **SEED-001** | a `metadata/seed-data/*.json` targets an entity the plugin doesn't ship and that isn't a known shared config entity, or `keyFields` look non-unique | ship the entity, or fix the key |
+| **JOB-001** | a new bespoke `ErpJobContribution` Java class where a generic sweep engine + JSON config would do | delete the Java, add a config row — see the job guides |
+| page-semantic-lint | a foreign-key field bound to a plain text/number input instead of `core.lookup`; decorative filters that aren't wired | use `core.lookup`; wire the filter to `externalFilter` |
+
+These are **warnings**, not hard failures — review each. But the platform's
+install-time equivalents of PAGE-DS-001 / I18N-001 / SEED-001 **do** block a bad
+install, so treat them as errors.
+
+## Wire it into CI
+
+The docs in this tree keep every example honest with a runner that validates
+every artifact and runs `erp plugin test`:
+
+```bash
+node developer-docs/examples/test-examples.mjs
+```
+
+```
+validating tutorial module artifacts against live schemas...
+  ok   tutorial/entities/oeq_equipment.json
+  ...
+running `erp plugin test` on the tutorial module...
+4 passed, 0 failed, 0 semantic warning(s), 3 skipped
+
+All examples valid.
+```
+
+Run it in CI on every change to `developer-docs/`. A broken example fails the
+build.
+
+## How to verify it worked
+
+A green `erp plugin test` and a green `test-examples.mjs`. That's the bar for
+"safe to publish".
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `erp plugin validate` says "no page JSON found" | you pointed it at the plugin root, not `spk-assembly` | pass `<plugin>/spk-assembly` |
+| `erp schema validate` fails on a page file | page files are wrapped; `--schema page` checks the inner contract | rely on `erp plugin validate` / `test` for pages |
+| lint clean locally, install still fails | a check the platform runs that the SDK doesn't (rare) | read the install error; report it |
+| `erp plugin test` skips `security-rule-scan` etc. | those need extra inputs | fine for a JSON-only plugin |
+
+## What to read next
+
+- [Publish and upgrade a plugin](./publish-and-upgrade.md)
+- [Wire a page's data](./wire-a-pages-data.md)
+- Troubleshooting: [known gotchas](../troubleshooting/known-gotchas.md)