@sparkerp/plugin-sdk 0.1.0

package/erp-cli/authoring-root.mjs

@@ -0,0 +1,344 @@
+/**
+ * resolveAuthoringRoot() — the single resource-root abstraction shared by the
+ * ERP developer CLI (tools/erp-cli/erp.mjs) and the MCP server
+ * (tools/erp-mcp-server/index.mjs).
+ *
+ * WHY THIS EXISTS
+ * A tenant / third-party plugin developer installs the SDK (CLI + MCP),
+ * `erp login`s to a deployed ERP, and authors plugins WITH NO ACCESS TO THE
+ * PLATFORM MONOREPO — platform source is secret to them. Before this module
+ * every schema/doc/example/catalog read in the CLI and MCP server was a
+ * hardcoded repo-relative path, so a packaged install had nothing to read.
+ *
+ * TWO MODES
+ *  - monorepo  (default when a repo checkout is detected, or ERP_SDK_MODE=monorepo):
+ *              EXACT prior behavior — read live from backend/platform-runtime/schema,
+ *              ai/, backend/modules, and re-derive the engine catalog from Java source.
+ *              Platform developers see everything, byte-identical.
+ *  - packaged  (ERP_SDK_MODE=packaged, or no repo present):
+ *              read ONLY from the shipped authoring bundle (erp-authoring-bundle/,
+ *              produced by `erp bundle build`), overlaid by a local cache dir
+ *              ~/.erp/cache/<envKey>/ populated by `erp env sync` (later batch).
+ *              NO Java source scan, ever, on the client.
+ *
+ * The classification boundary between the two = the secret-code boundary.
+ * Nothing under ai/, no Java, no internal gap-analysis doc is ever in the bundle.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(__dirname, "..", "..");
+
+// ---------------------------------------------------------------------------
+// Schema registry — every real, formal JSON Schema the platform ships today.
+// Single source of truth: both erp.mjs's SCHEMA_FILES and index.mjs's SCHEMAS
+// are derived from this so they can never drift, and the bundle emitter copies
+// exactly this set into erp-authoring-bundle/schemas/.
+// ---------------------------------------------------------------------------
+export const SCHEMA_REGISTRY = {
+  page: {
+    file: "frontend/packages/page-engine/schema/page-definition.schema.json",
+    description: "A page's rows/overlays/variants/designer metadata — the top-level page.json contract.",
+  },
+  "page-template": {
+    file: "frontend/packages/page-engine/schema/page-template.schema.json",
+    description: "A reusable page template (see the generic-capability generator pattern).",
+  },
+  "block-definition": {
+    file: "frontend/packages/block-engine/schema/block-definition.schema.json",
+    description: "A block TYPE's own declared property/event contract (what core.grid, core.container, etc. accept).",
+  },
+  "block-instance": {
+    file: "frontend/packages/block-engine/schema/block-instance-config.schema.json",
+    description: "One block INSTANCE inside a page (instanceId/blockType/properties/events) — same shape validate-page-properties.mjs checks.",
+  },
+  form: {
+    file: "frontend/packages/form-engine/schema/form-definition.schema.json",
+    description: "A form's field/section/validation contract.",
+  },
+  action: {
+    file: "frontend/packages/action-engine/schema/action-definition.schema.json",
+    description: "A page-JSON/UI action-chain definition (frontend action engine — distinct from the server-side Action Engine, see ai/patterns/action-engine-server-side.md).",
+  },
+  rule: {
+    file: "frontend/packages/rule-engine/schema/rule-definition.schema.json",
+    description: "Frontend rule-engine definition (page-level conditional visibility/computed-value rules).",
+  },
+  "plugin-manifest": {
+    file: "backend/platform-runtime/schema/spk-plugin-manifest.schema.json",
+    description: "A real .spk business-application plugin's own spk-assembly/plugin.json contract (id/version/permissions/roles/dependencies).",
+  },
+  "composite-pack-manifest": {
+    file: "frontend/packages/plugin-sdk/schema/plugin-manifest.schema.json",
+    description: "The newer composite-pack / Country-or-Industry-Pack / Code-Plugin-style manifest contract (contractVersion/publisher/distribution/12 extension-point contributions) — a genuinely different artifact type from an ordinary .spk plugin.json (use 'plugin-manifest' for that).",
+  },
+  "entity-definition": {
+    file: "backend/platform-runtime/schema/entity-definition.schema.json",
+    description: "A real Entity Engine entity (engine-entity) — fields/relationships, produces real DDL, zero hand-written CRUD Java.",
+  },
+  "entity-rule-definition": {
+    file: "backend/platform-runtime/schema/entity-rule-definition.schema.json",
+    description: "A declarative entity-lifecycle rule (engine-rule) — conditions/actions firing at BEFORE_CREATE/AFTER_UPDATE/etc.",
+  },
+  "workflow-definition": {
+    file: "backend/platform-runtime/schema/workflow-definition.schema.json",
+    description: "A real multi-stage approval workflow (engine-workflow) — stagesJson/tasksJson/transitionsJson (each itself a JSON-encoded string) + a top-level approvalPermissions array.",
+  },
+  menu: {
+    file: "backend/platform-runtime/schema/menu-definition.schema.json",
+    description: "Menu Designer's content model (@erp/menu-engine) — hierarchical sidenav tree (nodes/navigation/visibility/security/badge/personalization/advanced).",
+  },
+  "provider-definition": {
+    file: "backend/platform-runtime/schema/provider-definition.schema.json",
+    description: "Provider Designer's content model (ProviderAuthoringController) — kind/connectionRef/basePath/supports.",
+  },
+  "mobile-nav": {
+    file: "backend/platform-runtime/schema/mobile-nav-definition.schema.json",
+    description: "Mobile Navigation Designer's content model (@erp/mobile-nav-engine) — a FLAT item list (bottom-tabs/drawer/hybrid), deliberately distinct from menu-definition.",
+  },
+  "data-service-definition": {
+    file: "backend/platform-runtime/schema/data-service-definition.schema.json",
+    description: "Data Service layer's content model (engine-entity DataServiceSpec) — provider/entity/dataView source + filters/parameters/composite steps.",
+  },
+  "data-view-definition": {
+    file: "backend/platform-runtime/schema/data-view-definition.schema.json",
+    description: "Data View layer's content model (engine-entity DataViewSpec) — a real multi-table SQL join over plain physical tables.",
+  },
+  "report-definition": {
+    file: "backend/platform-runtime/schema/report-definition.schema.json",
+    description: "Report Designer's content model (@erp/report-engine) — band/element grid.",
+  },
+  "print-template-definition": {
+    file: "backend/platform-runtime/schema/print-template-definition.schema.json",
+    description: "Print Template Designer's content model (@erp/print-engine) — Report's band/element sibling with a physical mm page + merge-tag text. Dashboards have NO separate schema — use `page`.",
+  },
+  "connector-definition": {
+    file: "backend/platform-runtime/schema/connector-definition.schema.json",
+    description: "Generic External Provider Connector Engine's content model (engine-provider-connector) — domain/providerKey/connectorKind(DIRECT|HTTP)/baseUrl/auth/request-template/response-mapping.",
+  },
+  "plugin-seed-data": {
+    file: "backend/platform-runtime/schema/plugin-seed-data.schema.json",
+    description: "metadata/seed-data/*.json — Entity-Engine data rows a plugin seeds on install/upgrade, idempotently (upsert by keyFields). See ai/patterns/plugin-install-data-seeding.md.",
+  },
+  "entity-status-date-sweep-config": {
+    file: "backend/platform-runtime/schema/entity-status-date-sweep-config.schema.json",
+    description: "One config row for the generic engine-entity.status-date-sweep job — flip an entity's own status/flag field once its own date column crosses now (±day_offset days).",
+  },
+  "entity-aggregation-config": {
+    file: "backend/platform-runtime/schema/entity-aggregation-config.schema.json",
+    description: "One config row for the generic engine-entity.aggregation-sweep job — fold count/sum/avg/min/max across a source entity and upsert the result into a target entity.",
+  },
+  "entity-cadence-config": {
+    file: "backend/platform-runtime/schema/entity-cadence-config.schema.json",
+    description: "One config row for the generic engine-entity.cadence-generator job — create new target-entity rows on a cadence, source-driven or standalone, deduped.",
+  },
+  "entity-compliance-config": {
+    file: "backend/platform-runtime/schema/entity-compliance-config.schema.json",
+    description: "One config row for the generic engine-entity.compliance-sweep job — evaluate a rule-engine boolean expression against every row of an entity and flag/escalate offenders.",
+  },
+  "entity-cross-plugin-action-config": {
+    file: "backend/platform-runtime/schema/entity-cross-plugin-action-config.schema.json",
+    description: "One config row for the generic engine-entity.cross-plugin-action job — a trigger_entity row entering a triggering status fans out create/update onto every related_entity row keyed back to it (offboarding fan-out; trigger may be another plugin's entity).",
+  },
+  "entity-document-generator-config": {
+    file: "backend/platform-runtime/schema/entity-document-generator-config.schema.json",
+    description: "One config row for the generic engine-entity.document-generator job — generate a structured-data artifact (json/csv) per eligible row via the FileService, store it in a DMS cabinet, and stamp the file id onto the row.",
+  },
+};
+
+const REPO_REL_TO_NAME = Object.fromEntries(
+  Object.entries(SCHEMA_REGISTRY).map(([name, v]) => [v.file.replace(/\\/g, "/"), name]),
+);
+
+// ---------------------------------------------------------------------------
+// Mode detection + bundle / cache locations
+// ---------------------------------------------------------------------------
+const BUNDLE_DIR_DEFAULT = path.join(REPO_ROOT, "tools", "erp-authoring-bundle");
+// A packaged npm install (@erp/plugin-sdk) ships its own bundle/ sibling
+// directory next to erp-cli/ (mirrors tools/erp-cli + tools/erp-authoring-bundle
+// being siblings under tools/ in the monorepo) — see packages/erp-plugin-sdk.
+// Prefer it when present so a packaged install never depends on REPO_ROOT
+// resolving anywhere real.
+const OWN_BUNDLE_DIR = path.join(__dirname, "..", "bundle");
+
+export function bundleDir() {
+  if (process.env.ERP_BUNDLE_DIR) return path.resolve(process.env.ERP_BUNDLE_DIR);
+  if (existsSync(OWN_BUNDLE_DIR)) return OWN_BUNDLE_DIR;
+  return BUNDLE_DIR_DEFAULT;
+}
+
+export function cacheDir() {
+  return path.join(os.homedir(), ".erp", "cache", process.env.ERP_ENV_KEY || "default");
+}
+
+/** monorepo | packaged. ERP_SDK_MODE overrides; else auto-detect a repo checkout. */
+export function detectMode() {
+  const m = (process.env.ERP_SDK_MODE || "").toLowerCase();
+  if (m === "packaged") return "packaged";
+  if (m === "monorepo") return "monorepo";
+  return existsSync(path.join(REPO_ROOT, "backend", "platform-runtime", "schema")) ? "monorepo" : "packaged";
+}
+
+export function isPackaged() {
+  return detectMode() === "packaged";
+}
+
+/** Throw a clear, actionable error for a feature that genuinely needs the monorepo. */
+export function requireMonorepo(feature) {
+  if (isPackaged()) {
+    throw new Error(
+      `"${feature}" is not available in packaged SDK mode — it needs platform build tooling ` +
+        `(block-engine dist / page-validator / live engine-api logs) that is not shipped in the authoring bundle. ` +
+        `Deferred to a later SDK batch. Use schema/catalog/docs/examples/scaffold tools instead.`,
+    );
+  }
+}
+
+/** First existing path from the cache overlay then the bundle, else null. */
+function overlaid(relFromRoot) {
+  const c = path.join(cacheDir(), relFromRoot);
+  if (existsSync(c)) return c;
+  const b = path.join(bundleDir(), relFromRoot);
+  return existsSync(b) ? b : null;
+}
+
+// ---------------------------------------------------------------------------
+// Resource resolvers — the only functions callers should use
+// ---------------------------------------------------------------------------
+
+/** Absolute path to a schema file, by its registry name. */
+export function schemaPathByName(name) {
+  const entry = SCHEMA_REGISTRY[name];
+  if (!entry) throw new Error(`unknown schema "${name}". Known: ${Object.keys(SCHEMA_REGISTRY).join(", ")}`);
+  if (isPackaged()) {
+    const p = overlaid(path.join("schemas", `${name}.schema.json`));
+    if (!p) throw new Error(`schema "${name}" not found in authoring bundle (${bundleDir()}) — run \`erp bundle build\` or \`erp env sync\`.`);
+    return p;
+  }
+  return path.join(REPO_ROOT, entry.file);
+}
+
+/** Absolute path to a schema file addressed by its repo-relative path (reverse-maps to a name). */
+export function schemaPathByRepoRel(repoRel) {
+  const name = REPO_REL_TO_NAME[repoRel.replace(/\\/g, "/")];
+  if (name) return schemaPathByName(name);
+  // Not in the registry (e.g. a $defs-only helper schema) — monorepo only.
+  requireMonorepo(`schema file ${repoRel}`);
+  return path.join(REPO_ROOT, repoRel);
+}
+
+export function loadSchemaByName(name) {
+  return { name, path: SCHEMA_REGISTRY[name].file, description: SCHEMA_REGISTRY[name].description, schema: JSON.parse(readFileSync(schemaPathByName(name), "utf8")) };
+}
+
+/** Roots for `erp docs search` / `erp_search_docs`, each {dir, source, relBase}.
+ * relBase is what reported file paths are shown relative to — REPO_ROOT in
+ * monorepo mode (byte-identical to prior behavior), the doc dir in packaged mode. */
+export function docsSearchRoots() {
+  if (isPackaged()) {
+    const roots = [];
+    const cache = path.join(cacheDir(), "docs");
+    const bun = path.join(bundleDir(), "docs");
+    if (existsSync(cache)) roots.push({ dir: cache, source: "developer-docs (synced)", relBase: cache });
+    if (existsSync(bun)) roots.push({ dir: bun, source: "developer-docs (bundled)", relBase: bun });
+    return roots;
+  }
+  return [{ dir: path.join(REPO_ROOT, "ai"), source: "ai/domains doc", relBase: REPO_ROOT }];
+}
+
+/** backend/modules root for filename-substring example search. */
+export function examplesModulesRoot() {
+  if (isPackaged()) {
+    return path.join(bundleDir(), "examples", "backend", "modules");
+  }
+  return path.join(REPO_ROOT, "backend", "modules");
+}
+
+/** Absolute path to a curated example file addressed by its repo-relative path. */
+export function exampleFileAbs(repoRel) {
+  if (isPackaged()) {
+    return overlaid(path.join("examples", repoRel)) || path.join(bundleDir(), "examples", repoRel);
+  }
+  return path.join(REPO_ROOT, repoRel);
+}
+
+/** The frozen engine catalog (packaged mode only). Returns null in monorepo mode. */
+export function frozenCatalog() {
+  if (!isPackaged()) return null;
+  const p = overlaid("catalog.json");
+  if (!p) throw new Error(`engine catalog not found in authoring bundle (${bundleDir()}) — run \`erp bundle build\` or \`erp env sync\`.`);
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+
+export function readManifest() {
+  const p = overlaid("manifest.json") || path.join(bundleDir(), "manifest.json");
+  return existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : null;
+}
+
+// ---------------------------------------------------------------------------
+// Block-engine / page-engine module resolution — the packaged-mode port.
+//
+// The page validator (tools/page-validator/validate-page-properties.mjs) and
+// `erp blocks list` / erp_list_blocks need the REAL @erp/block-engine +
+// @erp/page-engine validators (validateInstanceConfig / validatePageDefinition
+// / coreBlockTypes / BlockRegistry). In monorepo mode those come straight from
+// each package's built dist (byte-identical to prior behavior). In packaged
+// mode they come from `validators/{block,page}-engine.mjs` — a self-contained
+// esbuild bundle of that exact same dist entrypoint (every workspace dep
+// inlined), emitted by `erp bundle build` and synced by `erp env sync`. Same
+// real code, no repo, no npm install, no build step on the client.
+// ---------------------------------------------------------------------------
+const BLOCK_ENGINE_DIST = "frontend/packages/block-engine/dist/index.js";
+const PAGE_ENGINE_DIST = "frontend/packages/page-engine/dist/index.js";
+
+function engineModuleUrl(kind) {
+  const packagedRel = path.join("validators", `${kind}-engine.mjs`);
+  const monorepoRel = kind === "block" ? BLOCK_ENGINE_DIST : PAGE_ENGINE_DIST;
+  if (isPackaged()) {
+    const p = overlaid(packagedRel);
+    if (!p) {
+      throw new Error(
+        `packaged-mode ${kind}-engine validator not found in authoring bundle (${bundleDir()}) — ` +
+          `run \`erp bundle build\` (monorepo) or \`erp env sync\` (deployed env) to populate validators/.`,
+      );
+    }
+    return pathToFileURL(p).href;
+  }
+  const abs = path.join(REPO_ROOT, monorepoRel);
+  if (!existsSync(abs)) {
+    throw new Error(
+      `@erp/${kind}-engine has no built dist at ${monorepoRel} — build it first ` +
+        `(same dist-only-resolution requirement as @erp/block-adapter-mui).`,
+    );
+  }
+  return pathToFileURL(abs).href;
+}
+
+export function blockEngineModuleUrl() {
+  return engineModuleUrl("block");
+}
+
+export function pageEngineModuleUrl() {
+  return engineModuleUrl("page");
+}
+
+/** Packaged mode: absolute path to the frozen block catalog (blocks.json). Monorepo: null (derive live from the dist). */
+export function blocksCatalogPath() {
+  if (!isPackaged()) return null;
+  const p = overlaid("blocks.json");
+  if (!p) {
+    throw new Error(
+      `block catalog (blocks.json) not found in authoring bundle (${bundleDir()}) — run \`erp bundle build\` or \`erp env sync\`.`,
+    );
+  }
+  return p;
+}
+
+/** A live/ per-environment JSON file synced from GET /api/v1/dev/bundle (packaged mode only). Returns null if absent. */
+export function readLiveJson(name) {
+  const p = overlaid(path.join("live", name));
+  return p && existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : null;
+}