@jxsuite/studio 2.4.3 → 4.0.0

package/src/services/jx-validate.ts

@@ -21,7 +21,7 @@ import coreDocumentSchema from "@jxsuite/schema/schema.json";
 import coreProjectSchema from "@jxsuite/schema/project-schema.json";
 
 type ValidateFn = ((doc: unknown) => boolean) & {
-  errors?: { instancePath?: string; message?: string }[] | null;
+  errors?: { instancePath?: string; message?: string; params?: Record<string, unknown> }[] | null;
 };
 
 /** Which of the two entry documents a validator covers. */
@@ -78,6 +78,16 @@ function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
   return compiling[kind];
 }
 
+/** A payload half that is usable as a JSON Schema — a non-empty, non-array object. */
+function asSchema(value: unknown): object | undefined {
+  return typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.keys(value).length > 0
+    ? (value as object)
+    : undefined;
+}
+
 /**
  * Swap in the active project's pre-bundled entry documents (the payload behind the platform's
  * `fetchProjectSchemas` member). Each half falls back to its core schema when absent, so a partial
@@ -90,16 +100,24 @@ function getValidator(kind: SchemaKind): Promise<ValidateFn | null> {
 export function applyProjectSchemas(
   schemas: { project?: unknown; document?: unknown } | null,
 ): boolean {
-  const document = (schemas?.document as object | undefined) ?? CORE.document;
-  const project = (schemas?.project as object | undefined) ?? CORE.project;
+  /*
+   * A payload half that is not a schema OBJECT falls back to core.
+   *
+   * `ajv.compile({})` succeeds and accepts everything, so a backend answering `null`, a string, or
+   * an error envelope under `document` would not fail loudly — it would install a validator that
+   * calls every document valid, and every consumer would go on trusting it.
+   */
+  const document = asSchema(schemas?.document) ?? CORE.document;
+  const project = asSchema(schemas?.project) ?? CORE.project;
+  const applied = document !== CORE.document || project !== CORE.project;
   if (document === active.document && project === active.project) {
-    return Boolean(schemas?.document || schemas?.project);
+    return applied;
   }
   active.document = document;
   active.project = project;
   compiling.document = null;
   compiling.project = null;
-  return Boolean(schemas?.document || schemas?.project);
+  return applied;
 }
 
 /** Restore the core schemas (project closed / tests). */
@@ -107,6 +125,17 @@ export function resetProjectSchemas(): void {
   applyProjectSchemas(null);
 }
 
+/**
+ * The keys ajv uses to name the property an error is ABOUT, in the order they can appear.
+ *
+ * `message` alone is not a diagnosis for any of these three. "must NOT have unevaluated properties"
+ * says a key is unrecognised without saying which key — and at the root of a `project.json` that is
+ * the difference between a fixable problem and a mystery. An imported project once produced that
+ * line three times over, naming nothing, and the only way to learn it meant `title`, `description`
+ * and `$style` was to compile the schema by hand.
+ */
+const ERROR_PROPERTY_KEYS = ["unevaluatedProperty", "additionalProperty", "missingProperty"];
+
 /**
  * Format ajv errors the way the agent loop consumes them (see ai-tools.ts
  * `translateValidationError`).
@@ -115,7 +144,11 @@ export function resetProjectSchemas(): void {
  * @returns {string[]} One formatted string per error
  */
 function formatErrors(validate: ValidateFn): string[] {
-  return (validate.errors || []).map((e) => `${e.instancePath || "(root)"}: ${e.message}`);
+  return (validate.errors || []).map((e) => {
+    const key = ERROR_PROPERTY_KEYS.find((name) => typeof e.params?.[name] === "string");
+    const property = key ? ` (${String(e.params?.[key])})` : "";
+    return `${e.instancePath || "(root)"}: ${e.message}${property}`;
+  });
 }
 
 /**
@@ -132,6 +165,25 @@ export async function validateDoc(doc: unknown): Promise<string[]> {
   return formatErrors(validate);
 }
 
+/**
+ * Validate a Jx document, distinguishing "valid" from "could not be checked".
+ *
+ * {@link validateDoc} fails OPEN — an unavailable validator answers `[]`, which is the same answer
+ * as "no errors". That is right where validation decorates an editor and wrong where it GATES a
+ * destructive step: a conversion that says "this will be a valid JSON document" on the strength of
+ * a schema it never compiled is the "never render 0" defect §9.1.1 forbids, one layer down.
+ *
+ * @param doc - Parsed document
+ * @returns The errors, `[]` when valid, or `null` when no validator could be compiled
+ */
+export async function validateDocOrNull(doc: unknown): Promise<string[] | null> {
+  const validate = await getValidator("document");
+  if (!validate) {
+    return null;
+  }
+  return validate(doc) ? [] : formatErrors(validate);
+}
+
 /**
  * Validate a `project.json` config against the active project schema. The per-project entry
  * document is what closes the composition (`unevaluatedProperties: false` over core + every enabled

package/src/services/project-adoption.ts

@@ -9,6 +9,11 @@
  * @license MIT
  */
 
+import { initProjectRepo } from "../files/files";
+import { beginBatch, endBatch, isBatching } from "../tabs/transact";
+import { workspace } from "../workspace/workspace";
+import type { Tab } from "../tabs/tab";
+
 let _adopter: ((root: string) => Promise<void>) | null = null;
 
 /** Register the project-open flow (studio.ts boot). */
@@ -29,3 +34,69 @@ export async function adoptProject(root: string): Promise<void> {
   }
   await _adopter(root);
 }
+
+/** What {@link adoptCreatedProject} observed, so a tool reports the outcome instead of the intent. */
+export interface AdoptOutcome {
+  /** The workspace is now on this root. False means the project exists but this window is not on it. */
+  adopted: boolean;
+  /** Why adoption failed, when it threw. Null when it did not (including when it silently did not). */
+  error: string | null;
+}
+
+/** The seams {@link adoptCreatedProject} runs through, so each caller keeps the one it already had. */
+export interface AdoptCreatedOptions {
+  /** The active tab, read AFTER adoption to re-anchor the agent loop's undo batch. */
+  getTab: () => Tab | null;
+  /** The project-open flow. Defaults to this module's late-bound {@link adoptProject}. */
+  adopt?: (root: string) => Promise<void>;
+  /** Version-control init. Defaults to `files/files.ts`'s `initProjectRepo`. */
+  initRepo?: (root: string) => Promise<boolean>;
+}
+
+/**
+ * Everything that must happen to a project the moment it exists: version control, then adoption.
+ *
+ * Extracted because `create_project` and `import_site` are the same act with different backends,
+ * and the wizard is a third caller of half of it. Two things it does are easy to leave out, and
+ * both were:
+ *
+ * - **Git init.** `specs/desktop.md` §4.5 is normative — _"On the create path, every source,
+ *   including Import and Agent, Studio therefore binds the backend to the new root (`activate`),
+ *   reads `gitStatus`, and runs `gitInit`."_ `initProjectRepo` had exactly two call sites, both in
+ *   the New Project modal, so a project the ASSISTANT bootstrapped was not a repository and nothing
+ *   said so. It runs first because it is what calls `platform.activate(root)`, which the open flow
+ *   below needs.
+ * - **Verifying.** `openRecentProject` swallows its failures into a status message, so a resolved
+ *   promise is not proof of adoption. The caller must be told which of the two happened.
+ *
+ * The batch dance is the third: the agent loop may hold an undo batch on the pre-adoption tab, and
+ * adoption replaces every tab in the workspace. Flush it, adopt, re-open one on whatever tab
+ * adoption left active.
+ *
+ * @param {string} root - Absolute root of the project that was just created.
+ * @param {AdoptCreatedOptions} opts
+ * @returns {Promise<AdoptOutcome>}
+ */
+export async function adoptCreatedProject(
+  root: string,
+  { getTab, adopt = adoptProject, initRepo = initProjectRepo }: AdoptCreatedOptions,
+): Promise<AdoptOutcome> {
+  // Never fails the create: a project that was written stays written (initProjectRepo notifies).
+  await initRepo(root);
+
+  const wasBatching = isBatching();
+  if (wasBatching) {
+    endBatch();
+  }
+  let adoptionError: string | null = null;
+  try {
+    await adopt(root);
+  } catch (error) {
+    adoptionError = error instanceof Error ? error.message : String(error);
+  }
+  if (wasBatching) {
+    beginBatch(getTab());
+  }
+
+  return { adopted: workspace.projectRoot === root, error: adoptionError };
+}

package/src/services/settings/definitions.ts

@@ -0,0 +1,181 @@
+/**
+ * The settings registry — every application setting Studio holds, declared once.
+ *
+ * Before this table the answer to "which settings roam, and what is each one's default" lived in
+ * four places: a `PERSISTED_SETTINGS_KEYS` array, a private `const` per key in each `*-settings.ts`,
+ * a bespoke getter/setter pair beside it, and whatever the getter's `||` happened to fall back to.
+ * Adding a roaming setting meant editing all four and hoping; the key strings themselves were
+ * duplicated between the array and the module that owned them.
+ *
+ * Two properties of this table are load-bearing rather than tidy:
+ *
+ * 1.  **Scope is declared, not inferred.** {@link USER_SETTINGS} is DERIVED from it, so a setting
+ *     roams because it says `scope: "user"` — not because someone remembered to add its key to a
+ *     second list. `device` is the honest name for the rest: panel geometry and a palette's MRU
+ *     describe *this window*, and a user with two windows open wants them to differ.
+ * 2.  **A default is not a value.** The default is what a *reader* sees when nothing is stored; it
+ *     is never itself stored. `getModel()` used to mask unset as `"gpt-4o"` with `||`, a form
+ *     prefilled from it, and Save wrote the mask back — which is how an install whose owner had
+ *     configured an entirely different provider was left holding `jx.ai.model: "gpt-4o"` and
+ *     nothing else. {@link readSetting} and {@link readStoredSetting} in `kernel.ts` are two
+ *     functions for exactly this reason.
+ *
+ * @license MIT
+ */
+
+/**
+ * Where a setting lives.
+ *
+ * `user` follows the author — every window, every project, and (where the platform has a backend
+ * store) every browser profile the launcher hands out. `device` stays where it was written.
+ */
+export type SettingScope = "user" | "device";
+
+/** One setting, as the registry declares it. */
+export interface SettingDefinition {
+  /** The storage key, in both localStorage and the backend map. */
+  key: string;
+  scope: SettingScope;
+  /** What a reader sees when nothing is stored. Never written — see the module docblock. */
+  default: string;
+  /**
+   * Whether the value is a credential.
+   *
+   * Nothing in the kernel treats a secret differently; the flag is what lets a surface refuse to
+   * print one, a diagnostic dump refuse to include one, and the Accounts list report _that_ one is
+   * held rather than what it is (`specs/studio.md` §15 rule 1).
+   */
+  secret?: boolean;
+  /**
+   * Canonicalise an incoming value before it is stored. Total: it is handed raw user input.
+   *
+   * Applied on write only. A value already on disk is returned as it was found, so a normalizer
+   * that tightens later cannot silently rewrite what someone else stored.
+   */
+  normalize?: (raw: string) => string;
+}
+
+/** Trim, and drop trailing slashes — an endpoint is a base, not a path. */
+function normalizeBaseUrl(raw: string): string {
+  return raw.trim().replace(/\/+$/, "");
+}
+
+/** Trim. Credentials are pasted, and a paste carries whitespace. */
+function trimmed(raw: string): string {
+  return raw.trim();
+}
+
+/**
+ * Every setting, keyed by the name the rest of the app refers to it by.
+ *
+ * Declared `as const satisfies` so each entry keeps its literal `key` for callers while still being
+ * checked against {@link SettingDefinition}.
+ */
+export const SETTINGS = {
+  aiBaseUrl: {
+    default: "",
+    key: "jx.ai.baseUrl",
+    normalize: normalizeBaseUrl,
+    scope: "user",
+  },
+  /**
+   * The provider key. Stays in the settings store rather than moving to the launcher's credential
+   * store: the webview is its legitimate consumer — it sends the key itself as `X-Api-Key` — so
+   * withholding it and then transmitting it would be the same trust boundary with more parts. See
+   * `specs/desktop.md` §3.6, which draws that line.
+   */
+  aiOpenAiKey: {
+    default: "",
+    key: "jx.ai.openaiKey",
+    normalize: trimmed,
+    scope: "user",
+    secret: true,
+  },
+  /**
+   * `"gpt-4o"` is what a sender falls back to, NOT a stored choice. A surface that writes back must
+   * read through `readStoredSetting`, or it persists a model the user never picked.
+   */
+  aiModel: {
+    default: "gpt-4o",
+    key: "jx.ai.model",
+    normalize: trimmed,
+    scope: "user",
+  },
+  /**
+   * The author's rebindings, as a JSON object of `command id → chords`.
+   *
+   * Roams, so a keyboard learned once is the keyboard everywhere. `normalize` is why the field
+   * exists on {@link SettingDefinition}: an empty override map is the absence of an override, and
+   * storing `"{}"` would make every window think a layer had been authored.
+   */
+  keybindings: {
+    default: "",
+    key: "jx.keybindings",
+    normalize: (raw) => (raw.trim() === "{}" ? "" : raw.trim()),
+    scope: "user",
+  },
+  /**
+   * The chrome theme.
+   *
+   * Read at module evaluation, before the first paint — `shell.ts` says a mismatch with the theme
+   * `index.html` hard-codes flashes the shell. That is the reason the kernel keeps a synchronous
+   * cache rather than awaiting the backend.
+   */
+  theme: {
+    default: "",
+    key: "jx-studio-theme",
+    normalize: trimmed,
+    scope: "user",
+  },
+  /**
+   * Whether the Files tree draws what `.gitignore` masks.
+   *
+   * Unset — the default — HIDES them, which is the whole point: a project root holds the author's
+   * forty documents and a tool's forty thousand, and the author already said which is which. The
+   * setting exists so that answer is not a trap. `.env`, a built `dist/` an author wants to read, a
+   * generated file being debugged: each is a legitimate reason to look at an ignored file, and a
+   * sidebar that cannot show one sends the author to a different program.
+   *
+   * Roams, because "show me everything" is a way of working rather than a property of a window.
+   */
+  showIgnoredFiles: {
+    default: "",
+    key: "jx.files.showIgnored",
+    normalize: trimmed,
+    scope: "user",
+  },
+  cfAccountId: {
+    default: "",
+    key: "jx.cf.accountId",
+    normalize: trimmed,
+    scope: "user",
+  },
+  cfToken: {
+    default: "",
+    key: "jx.cf.token",
+    normalize: trimmed,
+    scope: "user",
+    secret: true,
+  },
+} as const satisfies Record<string, SettingDefinition>;
+
+/** The registry's own names — `SETTINGS.aiModel`, not `"jx.ai.model"`. */
+export type SettingName = keyof typeof SETTINGS;
+
+/** Every declared setting, in declaration order. */
+export const ALL_SETTINGS: readonly SettingDefinition[] = Object.values(SETTINGS);
+
+/**
+ * The settings that roam, derived from {@link SETTINGS}.
+ *
+ * This replaces the hand-maintained `PERSISTED_SETTINGS_KEYS`. A setting joins it by declaring
+ * `scope: "user"` and by no other means, so the list cannot fall behind the table it describes.
+ */
+export const USER_SETTINGS: readonly SettingDefinition[] = ALL_SETTINGS.filter(
+  (definition) => definition.scope === "user",
+);
+
+/** The roaming keys as strings — what a backend map is keyed by. */
+export const USER_SETTING_KEYS: readonly string[] = USER_SETTINGS.map(
+  (definition) => definition.key,
+);