@sparkerp/plugin-sdk 0.1.0 → 1.1.0

package/erp-cli/erp.mjs

@@ -547,20 +547,57 @@ function envUseCommand(name, opts) {
 // back to / also including the local-repo-scoped substring match over
 // `backend/modules/*/spk-assembly/plugin.json` (still useful for plugins
 // that exist on disk but were never registered in the catalog).
-// [THIN] pull — reconstructs manifest+config+version state (everything
-// PluginInstallationController's GET actually returns) into a local file;
-// does NOT reconstruct the full spk-assembly page/workflow/entity source
-// tree (those live in per-artifact authoring controllers with different
-// shapes each — a genuinely separate, larger integration per artifact type,
-// disclosed as future work, not attempted here to avoid a half-correct
-// reconstruction). If the plugin is ALSO a registered registry package,
-// `erp registry get` (below) returns richer metadata (description,
-// license, dependencies, changelog) than the bare install-state row.
+// pull — default is [THIN]: manifest+config+version state (everything
+// PluginInstallationController's GET actually returns) into a local file.
+// `--full` (2026-09-23) is the real integration this used to disclose as
+// future work: walks every per-artifact authoring controller this plugin
+// owns and reconstructs the full spk-assembly page/workflow/entity source
+// tree — see `pluginPullFullReconstruction`'s own doc comment. THIN stays
+// the default (cheap, no N-artifact-type fan-out) for callers that only
+// want install-state (e.g. `erp plugin diff`'s own use of this same list
+// call). If the plugin is ALSO a registered registry package, `erp
+// registry get` (below) returns richer metadata (description, license,
+// dependencies, changelog) than the bare install-state row.
 // ---------------------------------------------------------------------------
+/**
+ * 2026-09-23 (direct user request — "developer should be able to list down
+ * all modules, then choose which module they want to checkout, similar to
+ * git commands") — the `git branch`/`git remote -v` step of the clone/
+ * checkout/add/commit/push flow below: a readable table by default so a
+ * developer can actually scan it before picking a `pluginId` for `erp
+ * plugin clone`, instead of a raw JSON dump of every manifest field. `--json`
+ * keeps the exact old output for any script already parsing it.
+ */
 async function pluginListCommand(opts) {
   const cfg = loadConfig();
   const list = await api(cfg, "GET", "/api/v1/authoring/plugins", { tenantIdOverride: opts.tenant });
-  console.log(JSON.stringify(list, null, 2));
+  if (opts.json) {
+    console.log(JSON.stringify(list, null, 2));
+    return;
+  }
+  const rows = list
+    .map((p) => {
+      const manifest = tryParseJson(p.manifestJson);
+      return {
+        pluginId: p.pluginId,
+        version: p.version,
+        state: p.state,
+        name: typeof manifest === "object" && manifest ? manifest.name || p.pluginId : p.pluginId,
+      };
+    })
+    .sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+  if (rows.length === 0) {
+    console.log("No plugins installed on this tenant.");
+    return;
+  }
+  const idWidth = Math.max(...rows.map((r) => r.pluginId.length), "PLUGIN ID".length);
+  const verWidth = Math.max(...rows.map((r) => r.version.length), "VERSION".length);
+  const stateWidth = Math.max(...rows.map((r) => r.state.length), "STATE".length);
+  console.log(`${"PLUGIN ID".padEnd(idWidth)}  ${"VERSION".padEnd(verWidth)}  ${"STATE".padEnd(stateWidth)}  NAME`);
+  for (const r of rows) {
+    console.log(`${r.pluginId.padEnd(idWidth)}  ${r.version.padEnd(verWidth)}  ${r.state.padEnd(stateWidth)}  ${r.name}`);
+  }
+  console.log(`\n${rows.length} plugin(s) installed. Checkout one: erp plugin clone <pluginId>`);
 }
 
 async function pluginSearchCommand(term, opts) {
@@ -691,6 +728,235 @@ async function pluginPullCommand(pluginId, opts) {
   writeFileSync(path.join(outDir, "config.json"), found.configJson || "{}", "utf8");
   writeFileSync(path.join(outDir, "installation-state.json"), JSON.stringify(found, null, 2), "utf8");
   console.log(`[THIN — manifest+config+state only, see erp.mjs header] Wrote ${outDir}/{plugin.json,config.json,installation-state.json}`);
+  if (opts.full) {
+    await pluginPullFullReconstruction(cfg, pluginId, found, outDir, opts);
+  } else {
+    console.log(`(pass --full for a real editable spk-assembly/ checkout — every page/menu/data-service/etc. this plugin owns, ready for 'erp plugin validate'/'build'/'publish')`);
+  }
+}
+
+/**
+ * `clone` (2026-09-23, direct user request — "similar to git commands:
+ * clone, checkout, add, commit, push") — `list` (git-`branch`-like) then
+ * `clone <pluginId>` (git-`clone`-like: a real local directory, full
+ * source, first thing you'd do with a plugin you want to work on) is the
+ * intended entry point; `pull --full` above still exists underneath it
+ * unchanged (this is a thin, differently-named wrapper, not a second
+ * implementation) for anyone already scripting against that name. Unlike
+ * `pull`, `clone` always does the full reconstruction — there's no reason
+ * to git-clone "thin".
+ * <p>
+ * Deliberately does NOT reinvent `add`/`commit`: the directory this writes
+ * is a real one on disk — `git init && git add . && git commit` right there
+ * already does real local staging/history perfectly, no fake local-only
+ * command needed. `push` already existed before this change (`erp plugin
+ * push`, an alias of `publish`) — that's the real "ship it" step once
+ * you're done editing.
+ */
+async function pluginCloneCommand(pluginId, opts) {
+  const cfg = loadConfig();
+  const list = await api(cfg, "GET", "/api/v1/authoring/plugins", { tenantIdOverride: opts.tenant });
+  const found = list.find((p) => p.pluginId === pluginId);
+  if (!found) throw new Error(`no installed plugin "${pluginId}" on this tenant — run: erp plugin list`);
+  const outDir = opts.out || path.join(process.cwd(), pluginId);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(path.join(outDir, "plugin.json"), found.manifestJson, "utf8");
+  writeFileSync(path.join(outDir, "config.json"), found.configJson || "{}", "utf8");
+  writeFileSync(path.join(outDir, "installation-state.json"), JSON.stringify(found, null, 2), "utf8");
+  await pluginPullFullReconstruction(cfg, pluginId, found, outDir, opts);
+  console.log(`\nNow a real local directory — e.g.:`);
+  console.log(`  cd ${outDir} && git init && git add . && git commit -m "Clone of ${pluginId}@${found.version}"`);
+}
+
+/**
+ * `checkout` (2026-09-23, completing the git-verb set: clone/checkout/add/
+ * commit/push) — `clone` always gets latest; this is `git checkout
+ * <ref>`'s counterpart when you want something OTHER than latest.
+ * <p>
+ * Disclosed, real limitation: there is no single "plugin version" snapshot
+ * to check out — `plugin.json`'s own `version` (e.g. "1.0.299") is bumped
+ * once per `.spk` release, but each individual artifact (a page, a data
+ * service, ...) versions independently on its OWN publish cadence (see
+ * `createDraft`'s own "next version for THIS name" comment elsewhere in
+ * this file) — there is no server-side mapping from "plugin was at 1.0.298"
+ * to "which version of every one of its 28 artifacts was live then". So
+ * `--version <n>` here means, per artifact independently: "the row whose
+ * own `version` field equals `n`, if this artifact has one that old —
+ * otherwise its latest" — an honest, disclosed best-effort, not a true
+ * point-in-time snapshot. Omitting `--version` is identical to `clone`.
+ */
+async function pluginCheckoutCommand(pluginId, opts) {
+  const cfg = loadConfig();
+  const list = await api(cfg, "GET", "/api/v1/authoring/plugins", { tenantIdOverride: opts.tenant });
+  const found = list.find((p) => p.pluginId === pluginId);
+  if (!found) throw new Error(`no installed plugin "${pluginId}" on this tenant — run: erp plugin list`);
+  const outDir = opts.out || path.join(process.cwd(), pluginId);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(path.join(outDir, "plugin.json"), found.manifestJson, "utf8");
+  writeFileSync(path.join(outDir, "config.json"), found.configJson || "{}", "utf8");
+  writeFileSync(path.join(outDir, "installation-state.json"), JSON.stringify(found, null, 2), "utf8");
+  if (opts.version) {
+    console.log(`== Checking out "${pluginId}" @ per-artifact version ${opts.version} where it exists (see this command's own doc comment — not a true point-in-time snapshot) ==`);
+  }
+  await pluginPullFullReconstruction(cfg, pluginId, found, outDir, opts);
+  console.log(`\nNow a real local directory — e.g.:`);
+  console.log(`  cd ${outDir} && git init && git add . && git commit -m "Checkout of ${pluginId}@${found.version}${opts.version ? ` (artifacts at v${opts.version} where available)` : ""}"`);
+}
+
+/**
+ * 2026-09-23 (direct user request, "developer should be able to checkout an
+ * existing installed plugin, work on it, then package and publish it — this
+ * should be part of the SDK CLI") — the real integration [THIN] pull's own
+ * header comment above disclosed as future work: walks every
+ * JsonArtifactAuthoringController-shaped artifact type this plugin owns
+ * (same `ownerPlugin` filter a Studio Explorer tree click already relies
+ * on) plus the two membership-only types (Application/Module) and this
+ * plugin's own i18n namespace, and writes a REAL local `spk-assembly/
+ * metadata/<type>/<name>.json` tree — the same on-disk shape/foldering an
+ * already-shipped module has (confirmed against hcm-foundation's own
+ * `metadata/` listing: application, data_service, data_view, i18n, menu,
+ * mobile_nav, module, page, provider). A developer edits under that real
+ * tree, then `erp plugin validate` / `erp plugin build` / `erp plugin
+ * publish` — the exact same pipeline every vendor module already ships
+ * through, no separate "customization" mechanism to learn.
+ * <p>
+ * Best-effort per artifact type: a 404/permission error on one type (e.g.
+ * an artifact type this tenant's license doesn't expose) is reported and
+ * skipped rather than aborting the whole checkout — matches every other
+ * "never let one projection helper break the read it decorates" posture
+ * elsewhere in this file.
+ */
+const PULL_ARTIFACT_TYPES = [
+  ["pages", "page"],
+  ["forms", "form"],
+  ["blocks", "block"],
+  ["dashboards", "dashboard"],
+  ["reports", "report"],
+  ["bi-reports", "bi_report"],
+  ["print-templates", "print_template"],
+  ["menus", "menu"],
+  ["mobile-navs", "mobile_nav"],
+  ["providers", "provider"],
+  ["data-services", "data_service"],
+  ["data-views", "data_view"],
+  ["rules", "rule"],
+  ["workflows", "workflow"],
+  ["actions", "action"],
+  ["applications", "application"],
+  ["modules", "module"],
+];
+
+function tryParseJson(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+}
+
+async function pluginPullFullReconstruction(cfg, pluginId, found, outDir, opts) {
+  const baseDir = path.join(outDir, "spk-assembly");
+  const metaDir = path.join(baseDir, "metadata");
+  const manifest = tryParseJson(found.manifestJson);
+  mkdirSync(baseDir, { recursive: true });
+  writeFileSync(path.join(baseDir, "plugin.json"), JSON.stringify(manifest, null, 2) + "\n", "utf8");
+  console.log(`-- spk-assembly/plugin.json (version ${manifest.version ?? found.version}) --`);
+
+  let totalArtifacts = 0;
+  for (const [urlSegment, folderName] of PULL_ARTIFACT_TYPES) {
+    let list;
+    try {
+      list = await api(cfg, "GET", `/api/v1/authoring/${urlSegment}?latestOnly=true`, { tenantIdOverride: opts.tenant });
+    } catch (e) {
+      console.log(`   ${urlSegment}: skipped (${e.message.split("\n")[0]})`);
+      continue;
+    }
+    if (!Array.isArray(list)) continue;
+    const owned = list.filter((r) => r.ownerPlugin === pluginId);
+    if (owned.length === 0) continue;
+    console.log(`-- ${urlSegment}: ${owned.length} owned by ${pluginId} --`);
+    for (const summary of owned) {
+      let targetId = summary.id;
+      if (opts.version) {
+        try {
+          const history = await api(cfg, "GET", `/api/v1/authoring/${urlSegment}/name/${encodeURIComponent(summary.name)}/history`, { tenantIdOverride: opts.tenant });
+          const match = Array.isArray(history) ? history.find((h) => String(h.version) === String(opts.version)) : null;
+          if (match) {
+            targetId = match.id;
+          } else {
+            console.log(`   ${summary.name}: no v${opts.version} in its own history — using latest (v${summary.version})`);
+          }
+        } catch {
+          // history lookup failed — fall through to latest, never block the checkout over it
+        }
+      }
+      const full = await api(cfg, "GET", `/api/v1/authoring/${urlSegment}/${targetId}`, { tenantIdOverride: opts.tenant });
+      const record = {
+        name: full.name,
+        description: full.description,
+        metadata: full.metadataJson ? tryParseJson(full.metadataJson) : undefined,
+        definition: tryParseJson(full.definitionJson),
+      };
+      const artifactDir = path.join(metaDir, folderName);
+      mkdirSync(artifactDir, { recursive: true });
+      writeFileSync(path.join(artifactDir, `${full.name}.json`), JSON.stringify(record, null, 2) + "\n", "utf8");
+      console.log(`   wrote ${folderName}/${full.name}.json (id ${full.id}, v${full.version})`);
+      totalArtifacts++;
+    }
+  }
+
+  // Entities are NOT a JsonArtifactAuthoringController subclass like the
+  // types above — no draft/publish/revision lifecycle, no `ownerPlugin`
+  // field at all, a different list endpoint (`/api/v1/entities`, not
+  // `/api/v1/authoring/entities` — that path 404s), and no `?latestOnly=`
+  // (there's only ever one row per entity). The closest thing to ownership
+  // is `category`, confirmed live to hold real plugin ids for entity-heavy
+  // modules (e.g. 47 rows with category "hcm-recruitment") — but it's a
+  // free-text taxonomy field, not an enforced foreign key the way
+  // `ownerPlugin` is, so this is a best-effort match, disclosed as such
+  // rather than presented as equally reliable.
+  try {
+    const entities = await api(cfg, "GET", "/api/v1/entities", { tenantIdOverride: opts.tenant });
+    const owned = Array.isArray(entities) ? entities.filter((r) => r.category === pluginId) : [];
+    if (owned.length > 0) {
+      console.log(`-- entities: ${owned.length} with category "${pluginId}" (best-effort — no real ownerPlugin field on this type) --`);
+      const artifactDir = path.join(metaDir, "entity");
+      mkdirSync(artifactDir, { recursive: true });
+      for (const summary of owned) {
+        const full = await api(cfg, "GET", `/api/v1/entities/${summary.id}`, { tenantIdOverride: opts.tenant });
+        writeFileSync(path.join(artifactDir, `${full.name}.json`), JSON.stringify(full, null, 2) + "\n", "utf8");
+        console.log(`   wrote entity/${full.name}.json (id ${full.id})`);
+        totalArtifacts++;
+      }
+    }
+  } catch (e) {
+    console.log(`   entities: skipped (${e.message.split("\n")[0]})`);
+  }
+
+  console.log(`-- i18n --`);
+  try {
+    const translations = await api(cfg, "GET", "/api/v1/authoring/translations", { tenantIdOverride: opts.tenant });
+    const enRow = translations.find((t) => t.locale === "en");
+    if (enRow) {
+      const allEntries = JSON.parse(enRow.entriesJson);
+      // A plugin's own spk-assembly i18n file ships only the keys IT owns
+      // (its artifact-name-prefixed namespace), never the tenant's whole
+      // translation bundle (~31k keys / 2.5MB on this env alone).
+      const ownKeys = Object.fromEntries(Object.entries(allEntries).filter(([k]) => k.startsWith(`${pluginId}.`)));
+      const i18nDir = path.join(metaDir, "i18n");
+      mkdirSync(i18nDir, { recursive: true });
+      writeFileSync(path.join(i18nDir, "en.json"), JSON.stringify(ownKeys, null, 2) + "\n", "utf8");
+      console.log(`   wrote i18n/en.json (${Object.keys(ownKeys).length} keys under "${pluginId}.*")`);
+    }
+  } catch (e) {
+    console.log(`   i18n: skipped (${e.message.split("\n")[0]})`);
+  }
+
+  console.log(`\n== Full checkout done: ${totalArtifacts} artifacts + plugin.json + i18n written to ${baseDir} ==`);
+  console.log(`Next: edit under ${metaDir}, then:`);
+  console.log(`  erp plugin validate ${outDir}`);
+  console.log(`  erp plugin build ${outDir} -o ${pluginId}-<version>.spk`);
+  console.log(`  erp plugin publish ${pluginId}-<version>.spk --env <name>   # e.g. local first, then prod`);
 }
 
 async function pluginDiffCommand(pluginId, opts) {
@@ -1397,6 +1663,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 +1887,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 });
@@ -2258,6 +2741,68 @@ async function pluginPublishFrontendCommand(backendModuleDir, opts) {
 // laptop -> VPS: publishes to the configured env's base_url with a device-flow
 // access token (never a hardcoded localhost:8080). `--env <name>` targets a
 // specific configured env; `--url` still overrides outright; ERP_TOKEN works for CI.
+// 2026-09-23 — real gap found live: `hcm-foundation`'s roles-permissions page
+// had FIVE page rows (versions 1-5, one per historical publish) all claiming
+// the identical route `/hcm-foundation/roles-permissions`, four of them
+// `deprecated`. The source only ever had ONE page file — this is an
+// install-time accumulation, not an authoring mistake `erp plugin
+// validate`/`erp_validate_plugin_pages` (both file-local, per-page schema
+// checks) could ever catch. Reported live as an intermittent "no page
+// registered for route" the frontend's own stale page-list cache could
+// reproduce. This checks the REAL, live, post-install state right after a
+// publish succeeds — the only point this class of bug is actually
+// detectable — instead of a developer discovering it from a confused user
+// report days later. Best-effort only: never fails the publish itself (the
+// install already succeeded by the time this runs), and silently skips when
+// `target` isn't a local directory with readable metadata/page/*.json files
+// (e.g. a prebuilt .spk with no adjacent source tree).
+async function checkDuplicateRoutesAfterPublish(cfg, target, opts) {
+  try {
+    const absTarget = path.resolve(target);
+    if (!existsSync(absTarget) || !statSync(absTarget).isDirectory()) return;
+    const manifestPath = findManifestPath(absTarget);
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const pluginId = manifest.id;
+    if (!pluginId) return;
+    const pageDir = path.join(path.dirname(manifestPath), "metadata", "page");
+    if (!existsSync(pageDir)) return;
+    const modules = new Set();
+    for (const f of readdirSync(pageDir).filter((f) => f.endsWith(".json"))) {
+      try {
+        const page = JSON.parse(readFileSync(path.join(pageDir, f), "utf8"));
+        for (const m of page.definition?.modules ?? []) modules.add(m);
+      } catch {
+        /* malformed page file is `erp plugin validate`'s job to catch, not this */
+      }
+    }
+    if (modules.size === 0) return;
+    const problems = [];
+    for (const moduleId of modules) {
+      const rows = await api(cfg, "GET", `/api/v1/authoring/pages?module=${encodeURIComponent(moduleId)}&latestOnly=true`, {
+        tenantIdOverride: opts.tenant,
+      });
+      const ownRows = (Array.isArray(rows) ? rows : []).filter((r) => r.ownerPlugin === pluginId);
+      const byRoute = new Map();
+      for (const r of ownRows) {
+        const pattern = r.route?.pattern;
+        if (!pattern) continue;
+        if (!byRoute.has(pattern)) byRoute.set(pattern, new Set());
+        byRoute.get(pattern).add(r.id);
+      }
+      for (const [pattern, ids] of byRoute) {
+        if (ids.size > 1) problems.push({ moduleId, pattern, ids: [...ids] });
+      }
+    }
+    if (problems.length > 0) {
+      console.log(`\nWARNING: ${problems.length} route(s) resolve to more than one "latestOnly" page — this is what produced a real "no page registered for route" bug (see [[page-resolution-version-only-dedup-gap]]):`);
+      for (const p of problems) console.log(`  ${p.pattern} (module ${p.moduleId}) -> page ids ${p.ids.join(", ")}`);
+      console.log(`  This is a server-side accumulation across past publishes, not something this publish itself broke. Clean up the extra rows via \`erp api delete /api/v1/authoring/pages/<id>\` after confirming (with a human) which id is the one currently live.`);
+    }
+  } catch {
+    /* best-effort post-check; never let it fail or obscure a successful publish */
+  }
+}
+
 async function pluginPublishCommand(target, opts) {
   const cfg = loadConfig();
   if (opts.env) {
@@ -2279,6 +2824,7 @@ async function pluginPublishCommand(target, opts) {
   console.log(`erp plugin publish: ${target} -> ${opts.url || env.baseUrl} (env "${env.name}", tenant ${h["X-Tenant-Id"]})`);
   if (opts.force) args.push("--force");
   runSpark(args);
+  if (!opts.dryRun && !process.exitCode) await checkDuplicateRoutesAfterPublish(cfg, target, opts);
 }
 
 // erp plugin force-unload <id> — rough-edge (b) recovery. Force-clears a
@@ -2841,6 +3387,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 +3939,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 +3973,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("");
@@ -3757,14 +4414,17 @@ const HELP = `erp — ERP Developer Platform CLI
   erp plugin list
   erp plugin search <term>
   erp plugin install <pluginId> [--manifest <path>]
-  erp plugin pull <pluginId> [--out <dir>]
+  erp plugin pull <pluginId> [--out <dir>]   (THIN — manifest+config+state only)
+  erp plugin pull <pluginId> --full [--out <dir>]   (real checkout — every page/menu/data-service/data-view/provider/i18n-key/etc. this plugin owns, written as a real editable spk-assembly/metadata/ tree under <out>/spk-assembly/ — edit it, then erp plugin validate/build/publish, same pipeline any vendor module ships through)
+  erp plugin clone <pluginId> [--out <dir>]   (git-clone-like: same full checkout as 'pull --full', always full, the intended entry point — list, clone, edit with real git (init/add/commit) in the cloned dir, build, push)
+  erp plugin checkout <pluginId> [--version <n>] [--out <dir>]   (git-checkout-like: same as clone, but --version <n> takes each owned artifact's own v<n> where it has one in its history, else its latest — NOT a true point-in-time plugin snapshot, see the command's own doc comment)
   erp plugin create <pluginId> [--name] [--schema] [--category] [--type <type>] [--runtime-mode embedded|service] [--service-port <n>]
   erp menu create <plugin-dir> <menu-id> [--display-name <name>] [--route <path>] [--icon <name>]   (scaffolds a real, schema-valid menu artifact — spark create leaves metadata/menu/ empty)
   erp plugin diff <pluginId>
   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 +4461,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]
@@ -3962,6 +4623,8 @@ async function main() {
     "plugin search": () => pluginSearchCommand(positional[0], opts),
     "plugin install": () => pluginInstallCommand(positional[0], opts),
     "plugin pull": () => pluginPullCommand(positional[0], opts),
+    "plugin clone": () => pluginCloneCommand(positional[0], opts),
+    "plugin checkout": () => pluginCheckoutCommand(positional[0], opts),
     "plugin create": () => pluginCreateCommand(positional[0], opts),
     "plugin diff": () => pluginDiffCommand(positional[0], opts),
     "spec generate": () => specGenerateCommand(positional[0], opts),
@@ -4005,6 +4668,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),