@sparkerp/plugin-sdk 0.1.0 → 1.0.0

package/erp-cli/erp.mjs

@@ -1397,6 +1397,222 @@ public class ${className} implements RestContribution {
   },
 };
 
+// 2026-09-23 — the other ~10 curated extension-point interfaces in
+// engine-plugin-api (`erp platform describe <Name>`) had NO real shipped
+// implementation anywhere in the codebase yet, unlike rest-contribution's
+// real HelloRestContribution.java model — so these are generated directly
+// from each interface's own real method/record signatures instead (never
+// invented syntax, just not "modeled on a real example" the way
+// rest-contribution's doc comment could honestly claim). Each nested record
+// the interface itself declares (e.g. PaymentProviderContribution.ChargeResult)
+// is referenced via its qualified inner-class import, exactly as javac requires.
+function contributionTemplate({ interfaceName, methods, extraImports = [] }) {
+  return {
+    describe: `A plugin-contributed ${interfaceName} — no real shipped implementation exists in this codebase yet, so this is generated directly from the real interface contract (see \`erp platform describe ${interfaceName}\`), not modeled on a working example.`,
+    render: ({ packageName, className, pluginId }) => `package ${packageName};
+
+import com.erp.platform.engine.plugin.api.${interfaceName};
+${extraImports.map((i) => `import ${i};`).join("\n")}
+import org.pf4j.Extension;
+
+/**
+ * Scaffolded by \`erp plugin scaffold\` from the real ${interfaceName}
+ * interface contract — no shipped reference implementation existed in this
+ * codebase yet (see this template's own note in erp.mjs). Replace every
+ * TODO with a real call to the actual provider this plugin integrates.
+ */
+@Extension
+public class ${className} implements ${interfaceName} {
+${methods}
+}
+`,
+  };
+}
+
+Object.assign(SCAFFOLD_TEMPLATES, {
+  "authentication-provider": contributionTemplate({
+    interfaceName: "AuthenticationProviderContribution",
+    extraImports: ["java.util.Optional"],
+    methods: `
+    @Override
+    public String providerId() {
+        return "${"${pluginId}"}";
+    }
+
+    @Override
+    public Optional<String> authenticate(String username, String credential) {
+        // TODO: call the real identity provider; return Optional.of(subjectId) on success.
+        return Optional.empty();
+    }`.replace("${pluginId}", "REPLACE_provider_id"),
+  }),
+  "banking-provider": contributionTemplate({
+    interfaceName: "BankingProviderContribution",
+    extraImports: ["java.math.BigDecimal", "java.time.LocalDate", "java.util.List"],
+    methods: `
+    @Override
+    public String providerId() {
+        return "REPLACE_provider_id";
+    }
+
+    @Override
+    public AccountBalance getBalance(byte[] decryptedCredentials, String accountId) {
+        // TODO: call the real banking API.
+        throw new UnsupportedOperationException("TODO");
+    }
+
+    @Override
+    public List<BankTransaction> getStatement(byte[] decryptedCredentials, String accountId, LocalDate from, LocalDate to) {
+        // TODO: call the real banking API.
+        throw new UnsupportedOperationException("TODO");
+    }
+
+    @Override
+    public PaymentResult initiatePayment(byte[] decryptedCredentials, String fromAccountId, String toAccountNumber, String toRoutingCode, BigDecimal amount, String currency, String reference, String remarks) {
+        // TODO: call the real banking API.
+        throw new UnsupportedOperationException("TODO");
+    }
+
+    @Override
+    public PaymentResult checkPaymentStatus(byte[] decryptedCredentials, String paymentReference) {
+        // TODO: call the real banking API.
+        throw new UnsupportedOperationException("TODO");
+    }`,
+  }),
+  "calendar-sync-provider": contributionTemplate({
+    interfaceName: "CalendarSyncProviderContribution",
+    extraImports: ["java.time.Instant"],
+    methods: `
+    @Override
+    public String providerId() {
+        return "REPLACE_provider_id";
+    }
+
+    @Override
+    public SyncResult createEvent(byte[] decryptedCredentials, String title, String description, Instant startAt, Instant endAt) {
+        // TODO: call the real calendar API.
+        throw new UnsupportedOperationException("TODO");
+    }
+
+    @Override
+    public SyncResult updateEvent(byte[] decryptedCredentials, String externalEventId, String title, String description, Instant startAt, Instant endAt) {
+        // TODO: call the real calendar API.
+        throw new UnsupportedOperationException("TODO");
+    }
+
+    @Override
+    public boolean deleteEvent(byte[] decryptedCredentials, String externalEventId) {
+        // TODO: call the real calendar API.
+        throw new UnsupportedOperationException("TODO");
+    }`,
+  }),
+  "embedding-provider": contributionTemplate({
+    interfaceName: "EmbeddingProviderContribution",
+    methods: `
+    @Override
+    public String providerId() {
+        return "REPLACE_provider_id";
+    }
+
+    @Override
+    public double[] embed(String text) {
+        // TODO: call the real embedding model.
+        throw new UnsupportedOperationException("TODO");
+    }`,
+  }),
+  "llm-provider": contributionTemplate({
+    interfaceName: "LlmProviderContribution",
+    methods: `
+    @Override
+    public String providerId() {
+        return "REPLACE_provider_id";
+    }
+
+    @Override
+    public String complete(String promptText) {
+        // TODO: call the real LLM.
+        throw new UnsupportedOperationException("TODO");
+    }`,
+  }),
+  "notification-provider": contributionTemplate({
+    interfaceName: "NotificationProviderContribution",
+    methods: `
+    @Override
+    public String channel() {
+        return "REPLACE_channel";
+    }
+
+    @Override
+    public boolean send(String recipient, String subject, String body) {
+        // TODO: call the real notification channel.
+        throw new UnsupportedOperationException("TODO");
+    }`,
+  }),
+  "payment-provider": contributionTemplate({
+    interfaceName: "PaymentProviderContribution",
+    methods: `
+    @Override
+    public String providerId() {
+        return "REPLACE_provider_id";
+    }
+
+    @Override
+    public ChargeResult charge(long amountMinorUnits, String currencyCode, String reference) {
+        // TODO: call the real payment gateway.
+        throw new UnsupportedOperationException("TODO");
+    }`,
+  }),
+  "search-provider": contributionTemplate({
+    interfaceName: "SearchProviderContribution",
+    extraImports: ["java.util.List"],
+    methods: `
+    @Override
+    public String providerId() {
+        return "REPLACE_provider_id";
+    }
+
+    @Override
+    public List<SearchHit> search(long tenantId, String query, int limit) {
+        // TODO: call the real search backend.
+        throw new UnsupportedOperationException("TODO");
+    }`,
+  }),
+  "storage-provider": contributionTemplate({
+    interfaceName: "StorageProviderContribution",
+    methods: `
+    @Override
+    public String providerId() {
+        return "REPLACE_provider_id";
+    }
+
+    @Override
+    public String store(long tenantId, byte[] content) {
+        // TODO: call the real storage backend; return its storagePath.
+        throw new UnsupportedOperationException("TODO");
+    }
+
+    @Override
+    public byte[] retrieve(String storagePath) {
+        // TODO: call the real storage backend.
+        throw new UnsupportedOperationException("TODO");
+    }`,
+  }),
+  "vector-search": contributionTemplate({
+    interfaceName: "VectorSearchContribution",
+    extraImports: ["java.util.List"],
+    methods: `
+    @Override
+    public String collectionId() {
+        return "REPLACE_collection_id";
+    }
+
+    @Override
+    public List<VectorHit> query(double[] queryEmbedding, int limit) {
+        // TODO: call the real vector index.
+        throw new UnsupportedOperationException("TODO");
+    }`,
+  }),
+});
+
 function pluginScaffoldCommand(extensionPoint, opts) {
   if (!extensionPoint || !SCAFFOLD_TEMPLATES[extensionPoint]) {
     console.log(`usage: erp plugin scaffold <extension-point> [--package <pkg>] [--class <Name>] [--plugin-id <id>] [--out <file.java>]\nKnown extension points: ${Object.keys(SCAFFOLD_TEMPLATES).join(", ")}`);
@@ -1405,7 +1621,8 @@ function pluginScaffoldCommand(extensionPoint, opts) {
   const tpl = SCAFFOLD_TEMPLATES[extensionPoint];
   const pluginId = opts.pluginId || "my-plugin";
   const packageName = opts.package || `com.example.${pluginId.replace(/[^a-zA-Z0-9]/g, "")}`;
-  const className = opts.class || "MyRestContribution";
+  const defaultClassName = "My" + extensionPoint.replace(/(^|-)([a-z])/g, (_, __, c) => c.toUpperCase());
+  const className = opts.class || defaultClassName;
   const rendered = tpl.render({ packageName, className, pluginId });
   if (opts.out) {
     mkdirSync(path.dirname(opts.out), { recursive: true });
@@ -2841,6 +3058,107 @@ async function blocksListCommand(opts) {
   console.log(`Pass --type <exact-or-partial-name> for one type's full definition (all designer/labelKey detail), e.g. \`erp blocks list --type core.lookup\`.`);
 }
 
+// ---------------------------------------------------------------------------
+// erp page check <route> — [REAL, added 2026-09-23]. A real browser render
+// check via Playwright (`playwright`, already a repo-root dependency), for
+// exactly the gap this session hit live: the API layer can be 100% verified
+// through `erp api`, yet a real production bug (the roles-permissions grid
+// showing zero rows despite a healthy 200 response with real data) only
+// exists in the DOM, invisible to any REST-only check. This generalizes the
+// one-off diagnostic scripts written ad hoc during that investigation into
+// one reusable command, instead of a new throwaway .mjs per page (see
+// [[feedback-common-playwright-script-not-per-page]]).
+//
+// Login is real browser form automation against {baseUrl}/app/admin/user/login
+// (not a session-storage shortcut) — the CLI's own stored device-flow token
+// doesn't map onto the frontend's session bootstrap without a much deeper
+// integration, and driving the real form is what actually exercises the
+// real login path a user hits. Requires --user/--password (or
+// ERP_UI_USER/ERP_UI_PASSWORD) since the CLI's stored credentials are a
+// token, never a password.
+// ---------------------------------------------------------------------------
+async function pageCheckCommand(routePath, opts) {
+  if (!routePath) {
+    console.log("usage: erp page check <route> [--user <email>] [--password <pw>] [--base-url <url>] [--timeout <ms>]\n  route: the app path after the base URL, e.g. /app/hcm/home/hcm-foundation/roles-permissions\n  credentials default to ERP_UI_USER/ERP_UI_PASSWORD env vars if not passed.");
+    return;
+  }
+  let chromium;
+  try {
+    ({ chromium } = await import("playwright"));
+  } catch {
+    console.log("`playwright` is not installed/resolvable from here — run `npm install` at the repo root first.");
+    process.exitCode = 1;
+    return;
+  }
+  const cfg = loadConfig();
+  const env = currentEnv(cfg);
+  const baseUrl = (opts.baseUrl || env.baseUrl).replace(/\/+$/, "");
+  const user = opts.user || process.env.ERP_UI_USER;
+  const password = opts.password || process.env.ERP_UI_PASSWORD;
+  const timeout = Number(opts.timeout) || 45000;
+
+  const consoleErrors = [];
+  const pageErrors = [];
+  const failedRequests = [];
+  const notableResponses = [];
+
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  page.setDefaultTimeout(timeout);
+  page.on("console", (msg) => { if (msg.type() === "error") consoleErrors.push(msg.text()); });
+  page.on("pageerror", (err) => pageErrors.push(err.message));
+  page.on("requestfailed", (req) => failedRequests.push(`${req.method()} ${req.url()} — ${req.failure()?.errorText ?? "unknown"}`));
+  page.on("response", async (res) => {
+    if (res.status() >= 400) {
+      notableResponses.push({ status: res.status(), url: res.url() });
+    }
+  });
+
+  try {
+    if (user && password) {
+      await page.goto(`${baseUrl}/app/admin/user/login`, { waitUntil: "networkidle" });
+      const inputs = page.locator("input");
+      await inputs.nth(0).fill(user);
+      await inputs.nth(1).fill(password);
+      await page.getByRole("button", { name: /login|sign in/i }).first().click();
+      await page.waitForTimeout(2000);
+    }
+
+    await page.goto(`${baseUrl}${routePath}`, { waitUntil: "networkidle" });
+    await page.waitForTimeout(1500);
+
+    const tableChecks = await page.locator("table").evaluateAll((tables) =>
+      tables.map((t, i) => ({
+        index: i,
+        headerCells: t.querySelectorAll("thead th").length,
+        bodyRows: t.querySelectorAll("tbody tr").length,
+      })),
+    );
+    const untranslatedKeys = await page.locator("body").evaluate((body) => {
+      const matches = body.innerText.match(/⟦[^⟧]+⟧/g);
+      return matches ? [...new Set(matches)] : [];
+    });
+    const bodyTextTail = (await page.locator("body").innerText()).slice(-600);
+
+    const report = {
+      route: routePath,
+      url: `${baseUrl}${routePath}`,
+      tables: tableChecks,
+      untranslatedI18nKeys: untranslatedKeys,
+      consoleErrors,
+      pageErrors,
+      failedRequests,
+      httpErrorResponses: notableResponses,
+      bodyTextTail,
+    };
+    console.log(JSON.stringify(report, null, 2));
+    const hasTableWithNoRows = tableChecks.some((t) => t.bodyRows === 0 && t.headerCells > 0);
+    if (hasTableWithNoRows || untranslatedKeys.length > 0 || pageErrors.length > 0) process.exitCode = 1;
+  } finally {
+    await browser.close();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // erp ai init / erp mcp install
 // [REAL] — scaffolds a plugin's ai/ subtree (agents.json/tools.json/
@@ -3292,8 +3610,18 @@ async function envSyncCommand(opts = {}) {
 // ---------------------------------------------------------------------------
 // erp docs gen-reference — turn the bundle's schemas/ into one Markdown page each
 // ---------------------------------------------------------------------------
+// A schema/property description can legitimately contain placeholder syntax
+// like "${field:<name>}" or "row #<key>" — real bug found 2026-09-22 (blocked
+// the whole developer-docs site build): embedded verbatim into a Markdown
+// table cell, VitePress's Vue-based compiler reads a bare `<name>` as an
+// unclosed HTML tag and fails the entire build, not just that page. Escape
+// angle brackets in any free-text description before it goes into the page.
+function escapeMdAngleBrackets(s) {
+  return String(s).replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 function renderSchemaMarkdown(name, schema) {
-  const desc = SCHEMA_REGISTRY[name]?.description || schema.description || "";
+  const desc = escapeMdAngleBrackets(SCHEMA_REGISTRY[name]?.description || schema.description || "");
   const lines = [
     "---",
     `title: ${name} schema`,
@@ -3316,7 +3644,7 @@ function renderSchemaMarkdown(name, schema) {
       const type = v.type ? (Array.isArray(v.type) ? v.type.join(" \\| ") : v.type) : v.$ref ? `\`${v.$ref}\`` : v.enum ? "enum" : "—";
       const notesParts = [];
       if (v.enum) notesParts.push("one of: " + v.enum.map((e) => `\`${e}\``).join(", "));
-      if (v.description) notesParts.push(String(v.description).replace(/\n+/g, " ").trim());
+      if (v.description) notesParts.push(escapeMdAngleBrackets(String(v.description).replace(/\n+/g, " ").trim()));
       lines.push(`| \`${k}\` | ${type} | ${required.has(k) ? "yes" : ""} | ${notesParts.join(" — ") || ""} |`);
     }
     lines.push("");
@@ -3764,7 +4092,7 @@ const HELP = `erp — ERP Developer Platform CLI
   erp spec generate <pluginId> [--out <file.md>]   (mechanically-derived entity/rule/page/permission inventory from LOCAL backend/modules/<id>/spk-assembly metadata — a starting point for ai/domains/*.md, not a replacement for its hand-curated narrative)
   erp platform catalog [--engine <engine-name>] [--refresh]   (mechanically-derived class/REST-mapping/Flyway-table inventory of every backend/platform-runtime/engine-* module — cached at ai/platform/engine-capability-catalog.json; erp docs search also searches this, labeled [live engine-* source], so a stale doc claim is never the only answer)
   erp platform describe <ClassName> [--refresh]   (real method signatures/field lists for a curated set of extension-point/gateway-client classes — *Contribution interfaces, WorkflowGatewayClient+PendingHumanTask/InstanceView/etc, DmsGatewayClient/CommunicationGatewayClient per-plugin copies — the concrete "what does this class actually contain" answer without opening the file; erp docs search also surfaces these, labeled [java contract])
-  erp plugin scaffold <extension-point> [--package <pkg>] [--class <Name>] [--plugin-id <id>] [--out <file.java>]   (emits a minimal, correctly-typed Java skeleton for a curated extension point, pulled from a real shipped implementation — currently: rest-contribution)
+  erp plugin scaffold <extension-point> [--package <pkg>] [--class <Name>] [--plugin-id <id>] [--out <file.java>]   (emits a minimal, correctly-typed Java skeleton for any curated extension point — 12 covered: rest-contribution, seed-data-config, authentication-provider, banking-provider, calendar-sync-provider, embedding-provider, llm-provider, notification-provider, payment-provider, search-provider, storage-provider, vector-search; rest-contribution/seed-data-config are modeled on a real shipped example, the other 10 are generated directly from the real interface contract since no shipped implementation exists yet — run \`erp plugin scaffold\` with no args for the full list)
   erp plugin validate <dir>
   erp plugin compile <source.tsx> [--out <page.json>]
   erp plugin test <dir>
@@ -3801,6 +4129,7 @@ const HELP = `erp — ERP Developer Platform CLI
   erp examples search <pattern> [--kind page|workflow|entities|provider] [--max <n>]  (real shipped metadata JSON across every backend/modules/* plugin, matched by filename/plugin name — pure-CLI mirror of the MCP erp_search_examples tool)
   erp examples patterns [--kind workflow]   (curated named SHAPES, not just filenames — e.g. single-stage-self-decide, multi-stage-linear, multi-stage-conditional-branching — each pointing at a real shipped file confirmed to have that shape)
   erp blocks list [--type <name>] [--category <cat>]  (the real widget/block catalog, derived live from @erp/block-engine's own registry — every property/event/output any block type accepts, no source reading needed; pass --type for one type's full definition)
+  erp page check <route> [--user <email>] [--password <pw>] [--base-url <url>] [--timeout <ms>]   (real browser render check via Playwright — logs in through the real login form if --user/--password given, navigates to <route>, reports every table's header/body-row counts, untranslated ⟦i18n.key⟧ placeholders, console errors, page errors, and failed/4xx+/5xx network responses as JSON; exits non-zero if a table has headers but zero rows, an i18n key leaked, or a page error fired — for catching DOM-only bugs no REST-level check like \`erp api\` can see)
   erp api get|post|put|delete <path> [--tenant <id>] [--body <json-string-or-@file>]   (authenticated call against ANY real backend endpoint using your logged-in session — for post-deploy verification: browse real entity records, live menu/workflow/artifact state, Data Service output. Never hand-write curl with guessed headers for this.)
   erp logs tail [--lines <n>] [--grep <text>] [--follow] [--file <path>]   (real server-side log, incl. full stack traces — join a failed call's own X-Correlation-Id response header against --grep to see exactly what the server saw for that request; default path is engine-api's own logs/engine-api.log)
   erp ai init [dir]
@@ -4005,6 +4334,7 @@ async function main() {
     "examples search": () => examplesSearchCommand(positional[0], opts),
     "examples patterns": () => examplesPatternsCommand(opts),
     "blocks list": () => blocksListCommand(opts),
+    "page check": () => pageCheckCommand(positional[0], opts),
     "api get": () => apiCallCommand("GET", positional[0], opts),
     "api post": () => apiCallCommand("POST", positional[0], opts),
     "api put": () => apiCallCommand("PUT", positional[0], opts),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkerp/plugin-sdk",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "ERP Developer Platform CLI + MCP server for authoring plugins against a deployed ERP with zero access to the platform monorepo (platform source is secret to third-party developers). Bundles an offline authoring snapshot (schemas/catalog/blocks/docs/examples/validators) so `erp schema list`, `erp blocks list`, `erp docs search`, and page validation all work before you ever run `erp login`.",
   "type": "module",
   "license": "MIT",