@sparkerp/plugin-sdk 1.0.0 → 1.1.0

package/bundle/catalog.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-09-23T05:56:28.078Z",
+  "generatedAt": "2026-09-23T08:53:08.093Z",
   "generatedBy": "erp platform catalog --refresh (tools/erp-cli/erp.mjs buildEngineCatalog)",
   "note": "Mechanically-derived from backend/platform-runtime/engine-*/src/main/java (regex class/interface/enum/record + @*Mapping scan) and every V*__*.sql Flyway migration under backend/platform-runtime — NOT a hand-maintained inventory, NOT a full Java AST parse. Regenerate with `erp platform catalog --refresh` whenever engine-* source changes.",
   "engineCount": 43,

package/bundle/docs/docs.json

@@ -44,6 +44,7 @@
         { "title": "Make a plugin work on desktop, tablet, and mobile", "path": "guides/responsive-plugin.md" },
         { "title": "Add a custom block (a \"widget\" you build yourself)", "path": "guides/add-a-custom-block.md" },
         { "title": "Build a plugin with custom React + Java code (L4)", "path": "guides/build-a-code-plugin.md" },
+        { "title": "Check out an installed plugin and work on it", "path": "guides/checkout-an-installed-plugin.md" },
         { "title": "Validate and test a plugin", "path": "guides/validate-and-test.md" },
         { "title": "Publish and upgrade a plugin", "path": "guides/publish-and-upgrade.md" },
         { "title": "Build a tenant extension service (L5)", "path": "guides/build-a-tenant-extension-service.md" },

package/bundle/docs/guides/checkout-an-installed-plugin.md

@@ -0,0 +1,151 @@
+---
+title: Check out an installed plugin and work on it
+audience: tenant
+---
+
+# Check out an installed plugin and work on it
+
+## What you're doing
+
+You already have a plugin **installed** on an environment — maybe you built
+it yourself weeks ago and lost the local source, maybe you inherited it from
+someone else, maybe you're fixing a real, confirmed bug in your own
+tenant-owned plugin. Either way you want a real local copy: something you
+can `git diff`, edit, and ship back — not a live-database patch, and not a
+raw dump of API responses.
+
+**Before you reach for this:** if what you actually want is to *extend* a
+shipped, vendor-owned application (HCM, CRM, ...) rather than edit a plugin
+you own, this is the wrong page — see
+[Extend a shipped application](./extend-a-shipped-application.md) instead.
+Editing another module's own source is never the right move for a feature
+request, only for a confirmed bug in a plugin that's genuinely yours.
+
+## The command set
+
+Modeled on git, on purpose — the mental model is the same one you already
+have:
+
+| git | erp | what it does |
+|---|---|---|
+| `git branch` / `git remote -v` | `erp plugin list` | Every plugin installed on the current env, as a readable table (`pluginId`, `version`, `state`, `name`) — pick one before cloning. `--json` for the raw response. |
+| `git clone` | `erp plugin clone <pluginId> [--out <dir>]` | A **real, full local checkout** — every page, menu, data service, data view, mobile nav, provider, application/module membership, and this plugin's own i18n keys it owns, written to `<out>/<pluginId>/spk-assembly/metadata/...` in the same on-disk shape a shipped module has. Always gets the latest version of every artifact. |
+| `git checkout <ref>` | `erp plugin checkout <pluginId> --version <n> [--out <dir>]` | Same full checkout as `clone`, but for each artifact independently, prefers version `n` from *that artifact's own* history if it has one that old, else falls back to latest. See the caveat below — this is not a single point-in-time snapshot. |
+| `git add` / `git commit` | plain `git`, inside the checked-out directory | It's a real folder now. `cd <pluginId> && git init && git add . && git commit -m "..."` gives you real, diffable history — no special erp command needed. |
+| `git push` | `erp plugin build <dir> -o out.spk` then `erp plugin publish out.spk --env <name>` (or `erp plugin push`, an alias) | Package your edited `spk-assembly/` into a `.spk` and ship it to an environment. See [Publish and upgrade a plugin](./publish-and-upgrade.md). |
+
+`erp plugin pull <pluginId>` (no `--full`) still exists separately — it's
+the *thin* form: just `plugin.json` + install config + install state, no
+artifact bodies. Useful for a quick "what version is installed, what's its
+manifest" check without the full fan-out `clone`/`checkout` do.
+
+## The complete example
+
+```bash
+# 1. See what's there
+erp plugin list
+
+# PLUGIN ID          VERSION   STATE      NAME
+# hcm-foundation     1.0.299   installed  HCM Foundation
+# office-equipment   1.0.0     installed  Office Equipment
+# ...
+
+# 2. Clone the one you own
+erp plugin clone office-equipment
+
+# == Checking out plugin "office-equipment" ==
+# -- spk-assembly/plugin.json (version 1.0.0) --
+# -- pages: 3 owned by office-equipment --
+#    wrote page/office-equipment-list.json (id 4021, v2)
+#    ...
+# -- i18n --
+#    wrote i18n/en.json (41 keys under "office-equipment.*")
+#
+# == Full checkout done: 9 artifacts + plugin.json + i18n written to office-equipment/spk-assembly ==
+#
+# Now a real local directory — e.g.:
+#   cd office-equipment && git init && git add . && git commit -m "Clone of office-equipment@1.0.0"
+
+# 3. Real git, from here on
+cd office-equipment
+git init && git add . && git commit -m "Clone of office-equipment@1.0.0"
+
+# 4. Edit under spk-assembly/metadata/, commit as you go
+#    (e.g. spk-assembly/metadata/page/office-equipment-list.json)
+git add -A && git commit -m "Add a status filter to the equipment list"
+
+# 5. Ship it — dev first, then prod
+erp plugin build . -o office-equipment-1.0.1.spk
+erp plugin publish office-equipment-1.0.1.spk --env dev
+#   ...verify it looks right...
+erp plugin publish office-equipment-1.0.1.spk --env prod
+```
+
+## What actually gets written
+
+```
+office-equipment/
+├── plugin.json                    ← THIN pull output (manifest only, kept for compat)
+├── config.json
+├── installation-state.json
+└── spk-assembly/                  ← the real, editable, buildable tree
+    ├── plugin.json
+    └── metadata/
+        ├── page/*.json
+        ├── menu/*.json
+        ├── mobile_nav/*.json
+        ├── provider/*.json
+        ├── data_service/*.json
+        ├── data_view/*.json
+        ├── application/*.json     ← membership rows, if this plugin owns any
+        ├── module/*.json
+        ├── entity/*.json          ← best-effort, see caveat below
+        └── i18n/en.json           ← only this plugin's own `<pluginId>.*` keys
+```
+
+Every artifact file is `{ name, description, metadata, definition }` — the
+same shape `erp plugin build` reads when packaging a `.spk`.
+
+## Known limits (disclosed, not hidden)
+
+- **`--version` is per-artifact, not a plugin-wide snapshot.** `plugin.json`'s
+  own `version` (e.g. `1.0.299`) is bumped once per `.spk` release, but each
+  individual artifact versions independently, on its own publish cadence.
+  There's no server-side record of "which version of every one of this
+  plugin's 28 artifacts was live when the plugin itself was at 1.0.298" — so
+  `checkout --version 4` takes artifact-level `v4` wherever that artifact
+  has one, and its latest otherwise. Good enough to inspect an older cut of
+  one screen; not a substitute for real git tags on your own commits going
+  forward.
+- **Entities are best-effort.** Unlike pages/menus/data-services/etc.,
+  entities have no `ownerPlugin` field at all — the closest available signal
+  is a free-text `category` field, matched against the plugin id. Confirmed
+  live to hold real plugin ids for entity-heavy modules, but it's not an
+  enforced foreign key.
+- **`erp plugin validate`** isn't available in packaged SDK mode (needs
+  platform build tooling not shipped in the authoring bundle) — validate
+  what you can with `erp schema validate <file> --schema <name>` per file
+  instead.
+
+## Common mistakes
+
+- **Cloning a vendor-owned plugin to "fix" a feature gap.** If it's not a
+  confirmed bug in code you own, use
+  [Extend a shipped application](./extend-a-shipped-application.md) instead
+  — a companion plugin, not an edit to someone else's source.
+- **Editing the THIN `plugin.json`/`config.json`/`installation-state.json`
+  files at the top level.** Those are install-state snapshots, not build
+  input — edit under `spk-assembly/metadata/` instead; that's what
+  `erp plugin build` actually reads.
+- **Forgetting `--env`.** `clone`/`checkout` read from whatever `erp env
+  use`'s current environment is (or `--env <name>` for one call) — cloning
+  from `prod` when you meant `dev` gets you prod's live content, not a
+  sandbox to break.
+
+## See also
+
+- [Publish and upgrade a plugin](./publish-and-upgrade.md) — the `build`/
+  `publish` half of this flow, in more depth.
+- [Extend a shipped application](./extend-a-shipped-application.md) — the
+  right tool when you don't own the plugin's source.
+- [Validate and test a plugin](./validate-and-test.md)

package/bundle/docs/guides/index.md

@@ -51,5 +51,6 @@ Every code sample is a real file under
 
 ## Ship it
 
+- [Check out an installed plugin and work on it](./checkout-an-installed-plugin.md)
 - [Validate and test a plugin](./validate-and-test.md)
 - [Publish and upgrade a plugin](./publish-and-upgrade.md)

package/bundle/manifest.json

@@ -1,13 +1,13 @@
 {
   "bundleVersion": "2026-09-23.1",
   "platformVersion": "0.0.0",
-  "generatedAt": "2026-09-23T05:56:28.964Z",
+  "generatedAt": "2026-09-23T08:53:09.048Z",
   "generatedBy": "erp bundle build (tools/erp-cli/erp.mjs bundleBuildCommand)",
   "schemaCount": 27,
-  "docCount": 248,
+  "docCount": 249,
   "exampleFileCount": 14,
   "blockCount": 124,
-  "catalogGeneratedAt": "2026-09-23T05:56:28.078Z",
+  "catalogGeneratedAt": "2026-09-23T08:53:08.093Z",
   "catalogEngineCount": 43,
   "catalogContractUnitCount": 74,
   "sdkMode": "packaged"

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) {
@@ -2475,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) {
@@ -2496,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
@@ -4085,7 +4414,10 @@ 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>
@@ -4291,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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkerp/plugin-sdk",
-  "version": "1.0.0",
+  "version": "1.1.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",