@jxsuite/studio 0.37.1 → 1.0.0

package/src/services/context-resolver.ts

@@ -0,0 +1,73 @@
+/**
+ * Context resolver — generic `#/$context/<pointer>` resolution over the project config
+ * (specs/extensions.md §9.1).
+ *
+ * Pointers walk the project config segment by segment. `{@param}` segments substitute values from a
+ * caller-provided scope (e.g. the form's current value record), and the `$formats` virtual root
+ * resolves to the registered format names instead of a project.json key.
+ */
+
+/** Options for {@link resolveContextPointer}. */
+export interface ResolveContextOptions {
+  /** The project configuration object the pointer walks over. */
+  projectConfig: Record<string, unknown>;
+  /** Scope record supplying `{@param}` substitutions (e.g. the enclosing form value). */
+  scope?: Record<string, unknown> | undefined;
+  /** Registered formats backing the `$formats` virtual root. */
+  formats?: { name: string }[] | undefined;
+}
+
+/** Matches a `{@param}` pointer segment, capturing the param name. */
+const PARAM_SEGMENT = /^\{@(\w+)\}$/;
+
+/**
+ * Resolve a `#/$context/<seg>/<seg>…` pointer.
+ *
+ * - `{@param}` segments substitute from `opts.scope`; an unresolvable param yields `undefined`.
+ * - The `$formats` virtual root returns the format names from `opts.formats`.
+ * - Every other pointer is a plain JSON-pointer walk over `opts.projectConfig` — no key is
+ *   special-cased, so both legacy (`contentTypes`) and newer (`content`) sections resolve alike.
+ *
+ * @param {string} pointer
+ * @param {ResolveContextOptions} opts
+ * @returns {unknown} The resolved value, or `undefined` when the pointer does not resolve.
+ */
+export function resolveContextPointer(pointer: string, opts: ResolveContextOptions): unknown {
+  if (!pointer.startsWith("#/$context/")) {
+    return undefined;
+  }
+
+  const segments: string[] = [];
+  for (const raw of pointer.slice("#/$context/".length).split("/")) {
+    const match = raw.match(PARAM_SEGMENT);
+    if (match) {
+      const value = opts.scope?.[match[1]!];
+      if (typeof value !== "string" && typeof value !== "number") {
+        return undefined;
+      }
+      const substituted = String(value);
+      if (!substituted) {
+        return undefined;
+      }
+      segments.push(substituted);
+    } else {
+      segments.push(raw);
+    }
+  }
+
+  if (segments[0] === "$formats") {
+    if (segments.length !== 1) {
+      return undefined;
+    }
+    return (opts.formats ?? []).map((format) => format.name);
+  }
+
+  let node: unknown = opts.projectConfig;
+  for (const segment of segments) {
+    if (node === null || typeof node !== "object") {
+      return undefined;
+    }
+    node = (node as Record<string, unknown>)[segment];
+  }
+  return node;
+}

package/src/services/data-service.ts

@@ -0,0 +1,155 @@
+/**
+ * Data-service — thin PAL wrapper over the optional data-surface members
+ * (dataConnections/dataConnectionTest/dataPush/dataRows/row CRUD/listSecrets/setSecrets).
+ *
+ * Every helper degrades cleanly when the platform omits the member family (older backends, cloud
+ * without DB reach): list-shaped calls resolve null/empty, action-shaped calls resolve an error
+ * result instead of throwing. Secret VALUES only ever flow INTO setSecrets — reads are names-only
+ * (specs/extensions.md §13).
+ */
+
+import { getPlatform } from "../platform";
+import type {
+  DataConnectionsResponse,
+  DataConnectionTestResult,
+  DataPushResult,
+  DataRowDelete,
+  DataRowInsert,
+  DataRowsQuery,
+  DataRowsResult,
+  DataRowUpdate,
+  SecretsSetRequest,
+  SecretsSetResponse,
+  StudioPlatform,
+} from "../types";
+
+/** The registered platform, or null before registration (early boot, bare tests). */
+function platformOrNull(): StudioPlatform | null {
+  try {
+    return getPlatform();
+  } catch {
+    return null;
+  }
+}
+
+/** True when the platform serves the data grid (the family's gating member is dataRows). */
+export function dataSurfaceAvailable(): boolean {
+  return typeof platformOrNull()?.dataRows === "function";
+}
+
+/** True when the platform can store secret values (backs the "secret" form control). */
+export function secretsAvailable(): boolean {
+  return typeof platformOrNull()?.setSecrets === "function";
+}
+
+/** Connections with configured state and table names; null when the backend lacks the route. */
+export async function fetchConnections(): Promise<DataConnectionsResponse | null> {
+  const platform = platformOrNull();
+  if (typeof platform?.dataConnections !== "function") {
+    return null;
+  }
+  return platform.dataConnections();
+}
+
+/** Probe one connection; degrades to an error result instead of throwing. */
+export async function testConnection(connection: string): Promise<DataConnectionTestResult> {
+  const platform = platformOrNull();
+  if (typeof platform?.dataConnectionTest !== "function") {
+    return { error: "Connection tests are not supported by this backend", ok: false };
+  }
+  try {
+    return await platform.dataConnectionTest(connection);
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error), ok: false };
+  }
+}
+
+/** Push table schemas (dryRun compiles the plan only); degrades to an error result. */
+export async function pushSchema(opts?: {
+  connection?: string;
+  dryRun?: boolean;
+}): Promise<DataPushResult> {
+  const platform = platformOrNull();
+  if (typeof platform?.dataPush !== "function") {
+    return { applied: false, errors: ["Schema push is not supported by this backend"], plan: [] };
+  }
+  try {
+    return await platform.dataPush(opts);
+  } catch (error) {
+    return {
+      applied: false,
+      errors: [error instanceof Error ? error.message : String(error)],
+      plan: [],
+    };
+  }
+}
+
+/** A required data member, throwing a uniform degradation error when absent. */
+function requireMember<K extends keyof StudioPlatform>(name: K): NonNullable<StudioPlatform[K]> {
+  const platform = platformOrNull();
+  const member = platform?.[name];
+  if (member === undefined || member === null) {
+    throw new Error(`The ${String(name)} surface is not supported by this backend`);
+  }
+  return member as NonNullable<StudioPlatform[K]>;
+}
+
+/** Page a table's rows (grid callers handle errors per load). */
+export function fetchRows(query: DataRowsQuery): Promise<DataRowsResult> {
+  return requireMember("dataRows")(query);
+}
+
+export function insertRow(req: DataRowInsert): Promise<{ row: Record<string, unknown> }> {
+  return requireMember("dataInsertRow")(req);
+}
+
+export function updateRow(req: DataRowUpdate): Promise<{ row: Record<string, unknown> }> {
+  return requireMember("dataUpdateRow")(req);
+}
+
+export function deleteRow(req: DataRowDelete): Promise<{ ok: boolean }> {
+  return requireMember("dataDeleteRow")(req);
+}
+
+/** Configured secret env-var NAMES; null when the backend has no secrets surface. */
+export async function listSecretNames(): Promise<string[] | null> {
+  const platform = platformOrNull();
+  if (typeof platform?.listSecrets !== "function") {
+    return null;
+  }
+  return platform.listSecrets();
+}
+
+/** Write/remove secrets through the platform store (values flow in, names come back). */
+export function saveSecrets(req: SecretsSetRequest): Promise<SecretsSetResponse> {
+  return requireMember("setSecrets")(req);
+}
+
+/**
+ * Derive the env-var NAME a secret-marked field stores its value under: CONSTANT_CASE of the entry
+ * key (falling back to the section key) plus the field key minus its `Env` suffix — e.g. connection
+ * "main" field "urlEnv" → "MAIN_URL"; section "auth" field "secretEnv" → "AUTH_SECRET". The NAME
+ * goes into project.json; the VALUE goes to setSecrets.
+ *
+ * @param {string} sectionKey
+ * @param {string | null} entryKey - The map-layout entry (connection) name, when any
+ * @param {string} fieldKey
+ * @returns {string}
+ */
+export function deriveSecretEnvName(
+  sectionKey: string,
+  entryKey: string | null,
+  fieldKey: string,
+): string {
+  const constant = (raw: string) =>
+    raw
+      .replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2")
+      .replaceAll(/[^A-Za-z0-9]+/g, "_")
+      .replaceAll(/^_+|_+$/g, "")
+      .toUpperCase();
+  const parts = [entryKey ?? sectionKey, fieldKey.replace(/Env$/, "")]
+    .map((part) => constant(part))
+    .filter(Boolean);
+  const name = parts.join("_") || "SECRET";
+  return /^\d/.test(name) ? `JX_${name}` : name;
+}

package/src/services/monaco-setup.ts

@@ -35,29 +35,78 @@ if (typeof document !== "undefined" && document.fonts?.ready) {
   });
 }
 
-// oxlint-disable-next-line typescript/no-unsafe-call, typescript/no-unsafe-member-access -- jsonDefaults is imported from Monaco's untyped ESM contribution (see @ts-expect-error above); no type declarations exist for this named export
-jsonDefaults.setDiagnosticsOptions({
-  allowComments: false,
-  schemas: [
-    {
-      fileMatch: [
-        "pages/*.json",
-        "pages/**/*.json",
-        "layouts/*.json",
-        "layouts/**/*.json",
-        "components/*.json",
-        "components/**/*.json",
-        "elements/*.json",
-        "elements/**/*.json",
-      ],
-      schema: jxSchema,
-      uri: "https://jxsuite.com/schema/v1",
-    },
-    {
-      fileMatch: ["project.json"],
-      schema: projectSchema,
-      uri: "https://jxsuite.com/schema/project/v1",
-    },
-  ],
-  validate: true,
-});
+/** Folder globs whose JSON files validate against the (per-project or core) document schema. */
+const DOCUMENT_FILE_MATCH = [
+  "pages/*.json",
+  "pages/**/*.json",
+  "layouts/*.json",
+  "layouts/**/*.json",
+  "components/*.json",
+  "components/**/*.json",
+  "elements/*.json",
+  "elements/**/*.json",
+];
+
+/**
+ * Register the JSON diagnostics schemas. Fetched per-project schemas are inline OBJECTS (never URLs
+ * — `enableSchemaRequest` stays off), so backends must serve them PRE-BUNDLED; the bundled core
+ * schemas remain the offline fallback.
+ */
+function applyJsonSchemas(documentSchema: unknown, projectJsonSchema: unknown) {
+  // oxlint-disable-next-line typescript/no-unsafe-call, typescript/no-unsafe-member-access -- jsonDefaults is imported from Monaco's untyped ESM contribution (see @ts-expect-error above); no type declarations exist for this named export
+  jsonDefaults.setDiagnosticsOptions({
+    allowComments: false,
+    schemas: [
+      {
+        fileMatch: DOCUMENT_FILE_MATCH,
+        schema: documentSchema,
+        uri: "https://jxsuite.com/schema/v1",
+      },
+      {
+        fileMatch: ["project.json"],
+        schema: projectJsonSchema,
+        uri: "https://jxsuite.com/schema/project/v1",
+      },
+    ],
+    validate: true,
+  });
+}
+
+// Bundled core schemas register at module init — the offline fallback every platform starts from.
+applyJsonSchemas(jxSchema, projectSchema);
+
+/**
+ * Swap Monaco's JSON schemas to the ACTIVE project's generated entry documents, fetched pre-bundled
+ * through the platform's optional `fetchProjectSchemas` member (dev server:
+ * `/__studio/project-schemas`; desktop: RPC into the project session). Call on project activation
+ * and after project.json `extensions` changes.
+ *
+ * @param {object} platform - The studio platform (only `fetchProjectSchemas` is consulted)
+ * @returns {Promise<boolean>} True when per-project schemas were applied; false on fallback
+ */
+export async function refreshProjectSchemas(platform: {
+  fetchProjectSchemas?: () => Promise<{ project?: unknown; document?: unknown }>;
+}): Promise<boolean> {
+  const fetcher = platform.fetchProjectSchemas;
+  if (!fetcher) {
+    return false;
+  }
+  let schemas: { project?: unknown; document?: unknown };
+  try {
+    schemas = (await fetcher.call(platform)) ?? {};
+  } catch {
+    // Editor degradation: keep the bundled core schemas.
+    return false;
+  }
+  const { document, project } = schemas;
+  if (!document && !project) {
+    return false;
+  }
+  applyJsonSchemas(document ?? jxSchema, project ?? projectSchema);
+  return true;
+}
+
+/** Restore the bundled core schemas (project closed / tests). */
+export function resetProjectSchemas(): void {
+  applyJsonSchemas(jxSchema, projectSchema);
+}