@jxsuite/studio 0.37.1 → 1.1.0

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/document-assistant.ts

@@ -12,16 +12,22 @@
 import { createChatState, createProxyStreamingClient, createToolRegistry } from "@jxsuite/ai";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
-import { activeTab, workspace } from "../workspace/workspace";
+import { activeTab, setWorkspaceProject, workspace } from "../workspace/workspace";
 import { toRaw } from "../reactivity";
+import { projectState, setProjectState } from "../store";
+import type { Tab } from "../tabs/tab";
 import { componentRegistry } from "../files/components";
 import { registerAiTools } from "./ai-tools";
+import { registerProjectTools } from "./ai-project-tools";
+import { createGatedToolRegistry } from "./gated-registry";
+import type { ToolAvailability } from "./gated-registry";
+import { adoptProject } from "./project-adoption";
 import { runAgentLoop } from "./tool-executor";
-import { buildSystemPrompt } from "./ai-system-prompt";
+import { AI_TOOL_TIERS, buildSystemPrompt, tierActive } from "./ai-system-prompt";
 import { getBaseUrl, getModel, getOpenAiKey } from "./ai-settings";
 import { trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
-import { openFileInTab } from "../files/files";
+import { openFileInTab, reloadFileInTab } from "../files/files";
 import * as sessionStore from "./ai-session-store";
 
 /**
@@ -51,8 +57,23 @@ function projectRoot() {
 export function createDocumentAssistant() {
   const chatState = createChatState({ model: getModel() });
 
-  const toolRegistry = createToolRegistry();
-  registerAiTools(toolRegistry, {
+  /** The persisted session backing the live chat; null = fresh unsaved chat. */
+  let sessionId: string | null = null;
+
+  const getProjectStyle = () =>
+    (workspace.projectConfig as ProjectConfig | null)?.style as Record<string, string> | undefined;
+
+  const findOpenTab = (path: string): Tab | null => {
+    for (const tab of workspace.tabs.values()) {
+      if (tab.documentPath === path) {
+        return tab;
+      }
+    }
+    return null;
+  };
+
+  const innerRegistry = createToolRegistry();
+  registerAiTools(innerRegistry, {
     getTab: () => activeTab.value,
     saveFile: async (relPath: string, content: string) => {
       const plat = getPlatform();
@@ -62,23 +83,72 @@ export function createDocumentAssistant() {
       doc: unknown,
     ) => Promise<{ ok: true } | { ok: false; error: string }>,
     openDocument: openFileInTab,
-    projectStyle: (workspace.projectConfig as ProjectConfig | null)?.style as
-      | Record<string, string>
-      | undefined,
+    getProjectStyle,
+    findOpenTab,
+    reloadTab: reloadFileInTab,
+  });
+  registerProjectTools(innerRegistry, {
+    getTab: () => activeTab.value,
+    renderCheck: renderCheck as (
+      doc: unknown,
+    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    getProjectStyle,
+    findOpenTab,
+    reloadTab: reloadFileInTab,
+    adoptProject,
+    // Re-key the live chat from the unscoped store to the adopted project so the bootstrap
+    // Conversation keeps persisting (saveSession drops writes for ids missing from the index).
+    onProjectAdopted: (root: string) => {
+      if (sessionId) {
+        sessionStore.moveSession("", root, sessionId);
+      }
+    },
+    onProjectConfigWritten: (config: object) => {
+      setWorkspaceProject(workspace.projectRoot, config);
+      if (projectState) {
+        setProjectState({ ...projectState, projectConfig: config as ProjectConfig });
+      }
+    },
   });
 
-  let controller: AbortController | null = null;
+  /*
+   * Gate tool advertisement/execution on live studio state, derived from the same tier table the
+   * system prompt renders — the model is never shown a tool it cannot execute. listForLLM() runs
+   * every agent-loop round, so a mid-loop create_project unlocks the higher tiers immediately.
+   */
+  const TIER_REQUIREMENTS = {
+    "no-project": "no project to be open (it bootstraps one)",
+    project: "an open project",
+    document: "an open document (use open_document first)",
+  } as const;
+  const availability = new Map<string, ToolAvailability>(
+    AI_TOOL_TIERS.map((t) => [
+      t.name,
+      {
+        when: () => tierActive(t.tier, Boolean(workspace.projectRoot), Boolean(activeTab.value)),
+        requires: TIER_REQUIREMENTS[t.tier],
+      },
+    ]),
+  );
+  const toolRegistry = createGatedToolRegistry(innerRegistry, availability);
 
-  /** The persisted session backing the live chat; null = fresh unsaved chat. */
-  let sessionId: string | null = null;
+  let controller: AbortController | null = null;
 
   function buildPrompt() {
     const tab = activeTab.value;
+    const inventory = projectState
+      ? [...projectState.dirs.values()]
+          .flat()
+          .filter((e) => e.type === "file")
+          .map((e) => e.path)
+      : undefined;
     return buildSystemPrompt({
       document: tab ? toRaw(tab.doc.document) : undefined,
       projectConfig: (workspace.projectConfig as ProjectConfig | null) || undefined,
       components: componentRegistry.length > 0 ? componentRegistry : undefined,
       projectRoot: workspace.projectRoot || undefined,
+      hasProject: Boolean(workspace.projectRoot),
+      ...(inventory && inventory.length > 0 ? { fileInventory: inventory } : {}),
     });
   }
 

package/src/services/gated-registry.ts

@@ -0,0 +1,72 @@
+/**
+ * Gated-registry.ts — state-aware tool advertisement for the AI assistant.
+ *
+ * Wraps a `@jxsuite/ai` ToolRegistry so each tool is only advertised to the LLM while its
+ * availability predicate holds (no project open → bootstrap tools only; project open → file tools;
+ * document open → document tools). `runAgentLoop` calls `listForLLM()` every round, so availability
+ * flips mid-loop: after `create_project` succeeds, the very next round advertises the file and
+ * document tools without any extra plumbing.
+ *
+ * Executing a tool whose predicate currently fails returns a tool error naming the missing state
+ * instead of throwing, so the agent loop can self-correct.
+ *
+ * @license MIT
+ */
+
+import type { ToolDefinition, ToolRegistry } from "@jxsuite/ai/tools";
+
+export interface ToolAvailability {
+  /** Whether the tool is currently advertised/executable. */
+  when: () => boolean;
+  /** Human-readable requirement, surfaced when execution is refused (e.g. "a project is open"). */
+  requires: string;
+}
+
+/**
+ * Wrap `inner` so tools listed in `availability` are only advertised/executable while their
+ * predicate holds. Tools without an entry are always available.
+ *
+ * @param {ToolRegistry} inner
+ * @param {Map<string, ToolAvailability>} availability
+ * @returns {ToolRegistry}
+ */
+export function createGatedToolRegistry(
+  inner: ToolRegistry,
+  availability: Map<string, ToolAvailability>,
+): ToolRegistry {
+  function isAvailable(name: string): boolean {
+    const gate = availability.get(name);
+    return gate ? gate.when() : true;
+  }
+
+  return {
+    register(tool: ToolDefinition) {
+      inner.register(tool);
+    },
+    list() {
+      return inner.list().filter((t) => isAvailable(t.name));
+    },
+    listForLLM() {
+      const available = new Set(this.list().map((t) => t.name));
+      return inner
+        .listForLLM()
+        .filter((t) => available.has((t as { function?: { name?: string } }).function?.name ?? ""));
+    },
+    getDefinition(toolName: string) {
+      return inner.getDefinition(toolName);
+    },
+    validate(toolName: string, args: object) {
+      return inner.validate(toolName, args);
+    },
+    async execute(toolName: string, args: object) {
+      if (inner.getDefinition(toolName) && !isAvailable(toolName)) {
+        const gate = availability.get(toolName);
+        return {
+          success: false,
+          error: `Tool "${toolName}" is not available right now — it requires ${gate?.requires ?? "a different studio state"}.`,
+        };
+      }
+      return inner.execute(toolName, args);
+    },
+  };
+}

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);
+}

package/src/services/preview-eval.ts

@@ -0,0 +1,68 @@
+/// <reference lib="dom" />
+/**
+ * Parent-side live expression preview (spec §19.9).
+ *
+ * Evaluates an expression node against the canvas iframe's last dataScope snapshot
+ * (tab.session.canvas.scope) on a structuredClone, so mutating operators are safe — they mutate the
+ * clone, never the live canvas. The engine's trace hook reports every sub-node's value keyed by its
+ * path within the tree; values are formatted to display strings at report time so later mutations
+ * of the clone cannot retroactively change a badge.
+ */
+
+import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { toRaw } from "../reactivity";
+// Imported for local use AND re-exported below so existing consumers keep their import site.
+// oxlint-disable-next-line unicorn/prefer-export-from
+import { formatPreviewValue } from "../utils/preview-format";
+
+import type { ExpressionNode } from "@jxsuite/runtime/expression";
+
+export interface ExpressionPreview {
+  /** Path-keyed display values: "" is the root node, "value/target" a nested operand, etc. */
+  values: Map<string, string>;
+  /** Evaluation error message, if the expression threw. */
+  error: string | null;
+  /** Whether the root operator mutates its target (badge renders as an effect, not a value). */
+  mutating: boolean;
+}
+
+// The formatter is shared with the in-iframe live evaluator: it lives in utils/preview-format.ts
+// (dependency-light, safe for the iframe bundle) and is re-exported here so existing consumers
+// Keep their import site.
+export { formatPreviewValue };
+
+/**
+ * Evaluate `node` against a scope snapshot for display. Returns null when no snapshot is available
+ * (canvas not yet rendered) — the editor renders no badges rather than wrong ones.
+ */
+export function previewExpression(
+  node: unknown,
+  scope?: Record<string, unknown> | null,
+): ExpressionPreview | null {
+  if (!scope || !node || typeof node !== "object" || !("operator" in node)) {
+    return null;
+  }
+
+  let state: Record<string, unknown>;
+  try {
+    // Callers hand over tab.session.canvas.scope, which the reactive session tree wraps in a
+    // Proxy — structuredClone rejects proxies, so unwrap to the raw snapshot first.
+    state = structuredClone(toRaw(scope));
+  } catch {
+    // Snapshot values are JSON-safe by construction (serialize-scope), but stay defensive.
+    return null;
+  }
+
+  const values = new Map<string, string>();
+  const expr = node as ExpressionNode;
+  let errorMessage: string | null = null;
+  try {
+    evaluateExpression(expr, state, null, undefined, {
+      report: (path, value) => values.set(path.join("/"), formatPreviewValue(value)),
+    });
+  } catch (error) {
+    errorMessage = error instanceof Error ? error.message : String(error);
+  }
+
+  return { error: errorMessage, mutating: isMutating(expr.operator), values };
+}

package/src/services/project-adoption.ts

@@ -0,0 +1,31 @@
+/**
+ * Project-adoption.ts — a late-bound slot for opening a freshly created project in this window.
+ *
+ * The AI `create_project` tool (services/ai-project-tools.ts) needs to run the full project-open
+ * flow (`openRecentProject` in studio.ts), but services must not import studio.ts — the entry
+ * module imports the services. studio.ts registers the adopter at boot; the tool calls
+ * `adoptProject(root)`.
+ *
+ * @license MIT
+ */
+
+let _adopter: ((root: string) => Promise<void>) | null = null;
+
+/** Register the project-open flow (studio.ts boot). */
+export function setProjectAdopter(fn: (root: string) => Promise<void>): void {
+  _adopter = fn;
+}
+
+/**
+ * Open the project at `root` in this window via the registered flow.
+ *
+ * @param {string} root - Absolute project root.
+ */
+export async function adoptProject(root: string): Promise<void> {
+  if (!_adopter) {
+    throw new Error(
+      "Project adoption is not available in this environment — open the project manually from the welcome screen.",
+    );
+  }
+  await _adopter(root);
+}