@sparkerp/plugin-sdk 0.1.0

package/erp-cli/example-patterns.mjs

@@ -0,0 +1,94 @@
+/**
+ * The curated, named-SHAPE example catalog shared by `erp examples patterns`
+ * (tools/erp-cli/erp.mjs) and the MCP server's `erp_examples_patterns` tool
+ * (tools/erp-mcp-server/index.mjs) — a single source of truth so a developer
+ * driving purely through the CLI and one driving purely through an MCP
+ * client see the identical catalog, never two copies that can drift. Pure
+ * data, no side effects, safe to import from either entrypoint (unlike
+ * importing erp.mjs itself, which runs its own CLI main() at import time).
+ */
+export const EXAMPLE_PATTERNS = {
+  workflow: [
+    {
+      name: "single-stage-self-decide",
+      description: "One actor both requests and immediately decides — models what would otherwise be a bare permission-gated direct action as a real, auditable, later-upgradable workflow instance. stagesJson: [\"only\"], transitionsJson: [] (no transitions needed, the one task's own decision ends the instance), approvalPermissions has exactly the role(s) that would have held the old direct-action permission. Caller: submit() then immediately decideHumanTask() in the same request.",
+      file: "backend/modules/hcm-employee/spk-assembly/metadata/workflow/employee.promotion-acknowledge.json",
+    },
+    {
+      name: "multi-stage-linear",
+      description: "A fixed sequence of real approvers, no branching. stagesJson: [\"manager\", \"hr\"], one transition (manager->hr) gated on {field:\"decision\",op:\"eq\",value:\"approved\"}, no transition out of the last stage — reaching it with no match completes the instance.",
+      file: "backend/modules/hcm-employee/spk-assembly/metadata/workflow/employee.resignation.json",
+    },
+    {
+      name: "multi-stage-conditional-branching",
+      description: "Stage routing depends on server-computed booleans passed via extraContext at startInstance (never omitted, so the condition evaluator never treats a missing field as false). transitionsJson conditions use {field,op,value} or {any:[...]}/{all:[...]} composition; a stage can be skipped entirely (hr->finance only if costCenterChanged||businessUnitChanged; hr->executive directly if neither changed but highImpact did). Empty-match at any stage completes the instance.",
+      file: "backend/modules/hcm-employee/spk-assembly/metadata/workflow/employee.movement.json",
+    },
+  ],
+  page: [
+    {
+      name: "related-record-lookup-field",
+      description: "2026-09-03, real gap found and fixed (a module built entirely by AI agents shipped every foreign-key field — employee_id, course_id, provider_id, etc. — as a bare text/number input the user had to type a raw numeric id into, module-wide, because this pattern was undiscoverable). ANY page field whose value is another entity's id must be a `core.lookup` block (or `core.select`/`core.autocomplete` for a small, static or already-loaded option set), never a plain text/number input. `core.lookup`'s properties: `value` (binding to the field), `recordType` (documentation-only label, e.g. \"Employee\"), `optionsSourceKey` (the REAL routing key — the `name` of a published Data Service artifact, spk-assembly/metadata/data_service/*.json, that this lookup calls server-side with a `search` parameter and expects back `{value,label}` rows). `committed` event fires with `event.new` = the picked record's id. If the target entity doesn't already have a search-shaped Data Service, author one first (`erp examples search employee-search --kind data-service` and `--kind data-view` show the real recipe: a `dataView` source + a `contains` filter on `${param.search}` + one required `search` parameter) — never skip straight to a text input because no Data Service exists yet.",
+      file: "backend/modules/hcm-employee/spk-assembly/metadata/page/promotions.json",
+    },
+    {
+      name: "resolved-reference-grid-column",
+      description: "2026-09-03, real gap found and fixed (a JSON-first module's grids showed a raw FK id — employee_id — in a `core.grid` column even though the SAME page's create dialog already used `core.lookup` for that field; the grid has no field-level lookup concept, only a `name`/`type`/`headerKey`/`renderAs` column spec). Do NOT bind a grid column or a detail-view value to a raw *_id field — check the entity's own field metadata first (`erp schema pull entity-definition` -> `properties.fields.items.properties.flags`'s own description covers this) for `flags.reference.entityType`; if present, GET .../records/query and GET .../records/{id} already return a sibling `<fieldName>_label` key (e.g. `employee_id` -> `employee_id_label`) with zero extra code — bind the column/value to that key instead. If the field ISN'T marked yet: set `\"flags\":\"{\\\"reference\\\":{\\\"entityType\\\":\\\"Employee\\\"}}\"` on it via `PUT /api/v1/entities/{id}/fields/{fieldId}` (entityType must be a REGISTERED provider — \"Employee\" is the only one shipped today) and the `_label` key appears automatically on the next read, batched once per page load, never per row.",
+      file: "backend/modules/hcm-compensation/spk-assembly/metadata/page/salary-planning.json",
+    },
+  ],
+  jobs: [
+    {
+      name: "n-days-before-reminder-sweep",
+      description: "2026-09-10. A 'remind me N days before <date>' background job needs ZERO Java — it is one entity_status_date_sweep_config row (engine-entity.status-date-sweep) with `day_offset` set. e.g. {entity_name:'hcm_asset', when_status_in:'AVAILABLE,ASSIGNED,IN_USE', date_field:'warranty_expiry_date', compare_op:'lte', day_offset:30, set_field:'warranty_alert_30d', set_status_to:'true', active:true} fires when warranty_expiry_date <= now+30d. Use a distinct flag field per window (30d/14d/7d) so windows are independently queryable and the reminder never touches the lifecycle `status` enum. Ship the rows via metadata/seed-data/*.json so they travel with the plugin. Schema: `erp_get_schema entity-status-date-sweep-config`. Doc: ai/patterns/generic-entity-status-date-sweep.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-sweep-configs.json",
+    },
+    {
+      name: "cross-row-aggregation-into-summary-entity",
+      description: "2026-09-10. A 'reconcile/roll-up count or total across many rows and store the result' job = one entity_aggregation_config row (engine-entity.aggregation-sweep), no Java. e.g. count hcm_asset grouped by status into a summary entity: {sweep_code:'asset-inventory-reconciliation', source_entity:'hcm_asset', aggregation:'count', group_by_field:'status', target_entity:'hcm_asset_reconciliation', target_key_field:'metric_key', target_key_prefix:'asset_status:', target_value_field:'metric_value', target_timestamp_field:'last_reconciled_at', active:true}. aggregation is count|sum|avg|min|max (last four over agg_field). Use target_key_prefix so several configs can share one summary entity. Schema: `erp_get_schema entity-aggregation-config`. Doc: ai/patterns/generic-aggregation-and-cadence-jobs.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-aggregation-configs.json",
+    },
+    {
+      name: "scheduled-record-generation-cadence",
+      description: "2026-09-10. A 'create new records on a schedule' job = one entity_cadence_config row (engine-entity.cadence-generator), no Java. STANDALONE (one row per tick): {cadence_code:'asset-audit-schedule', target_entity:'hcm_asset_audit', interval_days:90, dedupe_target_field:'cadence_marker', template_json:{audit_number:'AUDIT-${date}-${ts}', audit_name:'Scheduled Audit ${date}', status:'DRAFT'}}. SOURCE-DRIVEN (one row per due source row): add source_entity + source_date_field + due_within_days + field_map_json + dedupe_target_field=<a column holding the source id>. template_json string values support ${date} ${ts} ${uuid} ${sourceId}. Schema: `erp_get_schema entity-cadence-config`.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-cadence-configs.json",
+    },
+    {
+      name: "condition-based-compliance-flagging",
+      description: "2026-09-10 (Batch 3). A 'detect rows that violate a policy/compliance condition and flag them, or escalate them' job = one entity_compliance_config row (engine-entity.compliance-sweep), no Java. It evaluates a rule-engine boolean expression (the SAME platform ExpressionEvaluator cross-field validation and Formula fields use — whitelisted funcs only: daysBetween, now, etc.; no ternary/`in`/`^`) against each source row, with the row's own fields + `now` + optional `related_count` in scope. FLAG outcome: {compliance_code:'asset-assignment-compliance', source_entity:'hcm_asset', when_status_in:'ASSIGNED,IN_USE', condition_expr:'custody_acknowledged != true', set_field:'compliance_flag', set_value:'NON_COMPLIANT', active:true} (idempotent — skipped when the field already equals set_value). RELATED-COUNT (cross-record, e.g. license over-allocation): add related_count_entity + related_count_key_field (FK back to source id) + related_count_status_in, then use `related_count` in condition_expr (e.g. 'related_count > entitlement_quantity'). ESCALATION outcome (raise a row in a separate entity, deduped by source id): set escalation_entity + escalation_dedupe_field + field_map_json + escalation_template_json instead of set_field. Ship via metadata/seed-data/*.json + an AFTER_CREATE {type:EXECUTE_SERVICE, service:ensureEntityComplianceSweepJobRegistered} rule on entity_compliance_config. Schema: `erp_get_schema entity-compliance-config`. Doc: ai/patterns/generic-compliance-sweep-job.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-compliance-configs.json",
+    },
+    {
+      name: "target-key-field-id-rollup",
+      description: "2026-09-10 (Batch 5+6). To roll child line-items UP onto their own parent record (the true MaintenanceCostSyncJob shape — write synced_cost onto hcm_asset_maintenance keyed by its OWN id, not into a summary entity), set target_key_field:'id' on an entity_aggregation_config row: {sweep_code:'maintenance-cost-rollup', source_entity:'hcm_asset_maintenance_cost', aggregation:'sum', agg_field:'total_cost', group_by_field:'maintenance_id', target_entity:'hcm_asset_maintenance', target_key_field:'id', target_value_field:'synced_cost', target_timestamp_field:'cost_synced_at', active:true}. The bucket key (from group_by_field) IS the parent row's primary key; the fold is written straight onto that row (never a create). Leave target_key_prefix blank. Schema: `erp_get_schema entity-aggregation-config`. Doc: ai/patterns/generic-aggregation-and-cadence-jobs.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-aggregation-configs.json",
+    },
+    {
+      name: "cross-plugin-offboarding-fanout",
+      description: "2026-09-10 (Batch 5+6). 'When an employee is separated, auto-create asset return requests / license reclamation rows for everything they hold' = one entity_cross_plugin_action_config row (engine-entity.cross-plugin-action), no Java, no cross-plugin HTTP. {action_code:'asset-separation-return', trigger_entity:'employee', trigger_status_field:'employment_status', trigger_status_in:'TERMINATED,SEPARATED', trigger_key_field:'id', related_entity:'hcm_asset_allocation', related_match_field:'employee_id', related_status_in:'ALLOCATED,ACKNOWLEDGED,IN_USE', create_entity:'hcm_asset_return', create_dedupe_field:'allocation_id' (MUST be a numeric/long column), create_template_json:{status:'REQUESTED', reason:'EMPLOYEE_SEPARATION'}, create_field_map_json:{asset_id:'asset_id', employee_id:'employee_id'}, related_set_field:'status', related_set_value:'RETURN_PENDING', active:true}. The trigger entity can be owned by any plugin. Idempotent via the dedupe field. Schema: `erp_get_schema entity-cross-plugin-action-config`. Doc: ai/patterns/generic-cross-plugin-action-job.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-cross-plugin-configs.json",
+    },
+    {
+      name: "per-row-document-artifact-generation",
+      description: "2026-09-10 (Batch 5+6). 'Generate an audit report / certificate document per completed record and stash the file' = one entity_document_generator_config row (engine-entity.document-generator), no Java. {document_code:'asset-audit-report', source_entity:'hcm_asset_audit', when_status_in:'COMPLETED', target_file_field:'report_file_ref_id' (a TEXT column — its non-blank state IS the dedupe marker), format:'json', cabinet_id:<a real DMS cabinet id>, child_entity:'hcm_asset_audit_item', child_match_field:'audit_id', file_name_template:'asset-audit-${id}-${date}.json', active:true}. LIMITATION: the platform print-template render path (engine-print-export PlaywrightPdfRenderer) only renders synthetic sample data via the Studio app — it can't be driven headless against a real record — so this job emits a structured-data artifact (json/csv), not a rendered PDF; template_ref is reserved for when real-record binding ships. Schema: `erp_get_schema entity-document-generator-config`. Doc: ai/patterns/generic-document-generator-job.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-document-configs.json",
+    },
+    {
+      name: "heuristic-predictive-maintenance",
+      description: "2026-09-10 (Batch 5). PredictiveMaintenanceJob with NO ML: there is no tabular AI-inference seam (engine-ai-provider is text-gen/embedding only), so predictive-maintenance risk is scored as a DETERMINISTIC HEURISTIC config of the existing generic primitives — an entity_aggregation_config counting recent maintenance events per asset (target_key_field:'id' onto hcm_asset.recent_maintenance_count) plus an entity_compliance_config flagging hcm_asset.maintenance_risk='HIGH' when condition_expr combines real signals already in the data (recent_maintenance_count >= 3, or age past X% of expected_life_months, or open_maintenance_count >= 2). A real model plugs in later via the AiModelProvider seam with an entity_prediction_config, config-shape-compatible. Doc: ai/patterns/generic-compliance-sweep-job.md + the Batch 5 note in hcm-assets IMPLEMENTATION-GAPS.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-predictive-configs.json",
+    },
+    {
+      name: "install-lifecycle-data-seeding",
+      description: "2026-09-10. To make Entity-Engine data rows (especially rows in the SHARED platform config entities entity_status_date_sweep_config / entity_aggregation_config / entity_cadence_config / workflow_reminder_config) travel with the .spk instead of a manual per-tenant POST: add metadata/seed-data/<name>.json = {entity, keyFields:[...natural key...], source:'<pluginId>', rows:[...]}. PluginDataSeedInstaller upserts these on every install/upgrade/auto-provision, idempotently by keyFields (matched row updated only if a value changed, else inserted — never duplicated). Also ship metadata/entities/*.json for any entity/column the rows need, and metadata/rules/*.json AFTER_CREATE {type:EXECUTE_SERVICE, service:ensure<Job>Registered} to auto-register the job on first row. Schema: `erp_get_schema plugin-seed-data`. Doc: ai/patterns/plugin-install-data-seeding.md.",
+      file: "backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-sweep-configs.json",
+    },
+  ],
+  entities: [
+    {
+      name: "reference-display-label-field",
+      description: "2026-09-03. Any entity field whose value is another entity's real record id (a `long`-typed FK, e.g. `employee_id`) should carry `\"flags\":\"{\\\"reference\\\":{\\\"entityType\\\":\\\"Employee\\\"}}\"` in its field definition — this is the ONE line that turns on automatic id->display-name resolution platform-wide, no Java, no hand-written join. Once set, both the generic grid query (`GET .../records/query`) and single-record read (`GET .../records/{id}`) automatically add a `\"<fieldName>_label\"` key to every row/record where the id resolves (batched: one resolve call per distinct reference-flagged field per page load, never per row) — see `resolved-reference-grid-column` under `--kind page` for the consuming side. `entityType` must be a REGISTERED provider (a plugin that exposes its own `batch-names` endpoint) — \"Employee\" (backed by hcm-employee) is the only one shipped today; an unregistered entityType just produces no `_label` key, never an error.",
+      file: "backend/modules/hcm-compensation/spk-assembly/metadata/entities/hcm_salary_planning_entry.json",
+    },
+  ],
+};