@jxsuite/studio 3.0.0 → 4.1.0

package/src/services/import-client.ts

@@ -3,11 +3,21 @@
  * streaming fetch to some URL" — the dev server posts to its own origin, the desktop platforms post
  * to their token-gated loopback servers — so the request/parse/settle logic lives here once.
  *
- * The endpoint emits one JSON object per line: `progress` lines (forwarded to onProgress),
- * `heartbeat` keep-alives (ignored), and a terminal `done` ({root, config}) or `error` line.
+ * The endpoint emits one JSON object per line: `progress` lines (forwarded to onProgress), a
+ * `ready` line the moment the destination is an openable project (forwarded to onReady),
+ * `heartbeat` keep-alives (ignored), and a terminal `done` ({root, config, result}) or `error`
+ * line. `result` is optional — a backend that does not send one is not broken, and every caller
+ * treats its absence as "the run happened, and it did not say what it found". `ready` is optional
+ * for the same reason: an older backend simply never sends one, and the caller opens the project at
+ * the end as it always did.
  */
 
-import type { ImportProgressEvent, ImportSiteOptions } from "../types";
+import type {
+  ImportProgressEvent,
+  ImportReadyEvent,
+  ImportSiteOptions,
+  ImportSiteSummary,
+} from "../types";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
 /**
@@ -27,6 +37,7 @@ interface StreamLine {
   total?: number;
   root?: string;
   config?: ProjectConfig;
+  result?: ImportSiteSummary;
   error?: string;
 }
 
@@ -37,13 +48,17 @@ interface StreamLine {
  * @param {ImportSiteOptions} opts — the import request; `apiKey`/`baseUrl` travel as headers
  * @param {(evt: ImportProgressEvent) => void} onProgress
  * @param {AbortSignal} [signal]
+ * @param {(evt: ImportReadyEvent) => void} [onReady] — fires once, as soon as the destination holds
+ *   an openable project. Minutes before `done` on a real crawl, which is the whole reason it
+ *   exists.
  */
 export async function streamImport(
   endpoint: string,
   opts: ImportSiteOptions,
   onProgress: (evt: ImportProgressEvent) => void,
   signal?: AbortSignal,
-): Promise<{ root: string; config: ProjectConfig }> {
+  onReady?: (evt: ImportReadyEvent) => void,
+): Promise<{ root: string; config: ProjectConfig; result?: ImportSiteSummary }> {
   const headers: Record<string, string> = { "Content-Type": "application/json" };
   if (opts.apiKey) {
     headers["X-Api-Key"] = opts.apiKey;
@@ -59,7 +74,13 @@ export async function streamImport(
       depth: opts.depth,
       maxPages: opts.maxPages,
       aiComponents: opts.aiComponents,
+      ...(opts.breakpoints === undefined ? {} : { breakpoints: opts.breakpoints }),
       ...(opts.model === undefined ? {} : { aiModel: opts.model }),
+      ...(opts.verify === undefined ? {} : { verify: opts.verify }),
+      ...(opts.verifyThreshold === undefined ? {} : { verifyThreshold: opts.verifyThreshold }),
+      ...(opts.verifyMinFidelity === undefined
+        ? {}
+        : { verifyMinFidelity: opts.verifyMinFidelity }),
     }),
     headers,
     method: "POST",
@@ -85,7 +106,7 @@ export async function streamImport(
   const reader = res.body.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
-  let result: { root: string; config: ProjectConfig } | null = null;
+  let result: { root: string; config: ProjectConfig; result?: ImportSiteSummary } | null = null;
   /*
    * Lines the parser could not read. Tolerating one is right — an import that ran for two minutes
    * should not die on a garbled progress line — but doing it *silently* is not: the import then
@@ -113,8 +134,14 @@ export async function streamImport(
         ...(parsed.current === undefined ? {} : { current: parsed.current }),
         ...(parsed.total === undefined ? {} : { total: parsed.total }),
       });
+    } else if (parsed.type === "ready" && parsed.root !== undefined) {
+      onReady?.({ root: parsed.root });
     } else if (parsed.type === "done" && parsed.root !== undefined && parsed.config) {
-      result = { root: parsed.root, config: parsed.config };
+      result = {
+        root: parsed.root,
+        config: parsed.config,
+        ...(parsed.result === undefined ? {} : { result: parsed.result }),
+      };
     } else if (parsed.type === "error") {
       throw new Error(parsed.error || "Import failed");
     }

package/src/services/import-run.ts

@@ -0,0 +1,158 @@
+/**
+ * Import-run.ts — the live state of a site import, for the transcript to draw.
+ *
+ * An import takes minutes and reports a line at a time. Those lines used to render into the New
+ * Project modal and die with it: a successful import destroyed its own account of what it had done
+ * at the moment it handed off. Now the run belongs to a tool call, so the record is keyed by that
+ * call's id and the chip and its progress are one thing rather than two.
+ *
+ * Reactive, so `panels/ai-panel.ts`'s watcher repaints on it through the same rAF coalescer that
+ * carries streaming tokens — a crawl emitting a line per page cannot outrun the frame rate.
+ *
+ * @license MIT
+ */
+
+import { reactive } from "../reactivity";
+
+import type { ImportProgressEvent } from "../types";
+
+/**
+ * Lines kept per run.
+ *
+ * A wide crawl emits one per page plus one per asset batch, and every line is also held in the
+ * session's localStorage budget once the tool result lands — so there is a ceiling, and it is here.
+ * It was 200 back when the view showed the last SIX of them and the rest existed only to be
+ * summarised; the transcript now renders the whole log in a scroller the reader owns, so the number
+ * that matters is how far back they can scroll.
+ */
+export const MAX_LOG_LINES = 500;
+
+export interface ImportRunRecord {
+  /** The tool-call id — the join key with the chip the transcript draws. */
+  id: string;
+  url: string;
+  directory: string;
+  phase: string;
+  message: string;
+  current: number | null;
+  total: number | null;
+  log: ImportProgressEvent[];
+  /** Lines the pipeline marked with `⚠`, kept apart so the summary can name them. */
+  warnings: string[];
+  status: "running" | "done" | "failed" | "stopped";
+  error: string;
+}
+
+/**
+ * One run at a time, because one project is created at a time and `import_site` is `no-project`
+ * tiered. Keyed rather than bare so a finished run still renders under its own chip after the next
+ * one starts, which is what makes the transcript readable after two attempts.
+ */
+const runs = reactive<{ records: ImportRunRecord[] }>({ records: [] });
+
+/** Runs kept before the oldest is dropped. Two attempts and a retry is the realistic ceiling. */
+const MAX_RUNS = 5;
+
+/** Aborts the in-flight run. Owned here because `ToolRegistry.execute` cannot be handed a signal. */
+let controller: AbortController | null = null;
+
+/**
+ * Open a run record and return the signal its request should carry.
+ *
+ * @param {string} id - The tool-call id.
+ * @param {{ url: string; directory: string }} init
+ * @returns {AbortSignal}
+ */
+export function beginImportRun(id: string, init: { url: string; directory: string }): AbortSignal {
+  controller?.abort();
+  controller = new AbortController();
+  runs.records.push({
+    current: null,
+    directory: init.directory,
+    error: "",
+    id,
+    log: [],
+    message: "Starting…",
+    phase: "start",
+    status: "running",
+    total: null,
+    url: init.url,
+    warnings: [],
+  });
+  if (runs.records.length > MAX_RUNS) {
+    runs.records.shift();
+  }
+  return controller.signal;
+}
+
+/**
+ * Record one progress line against a run.
+ *
+ * @param {string} id
+ * @param {ImportProgressEvent} evt
+ */
+export function recordImportProgress(id: string, evt: ImportProgressEvent): void {
+  const record = runs.records.find((r) => r.id === id);
+  if (!record) {
+    return;
+  }
+  record.phase = evt.phase;
+  record.message = evt.message;
+  record.current = evt.current ?? null;
+  record.total = evt.total ?? null;
+  record.log.push(evt);
+  if (record.log.length > MAX_LOG_LINES) {
+    record.log.shift();
+  }
+  /* The pipeline reports a soft failure by prefixing its progress line, and `ImportSiteResult`'s
+     own `warnings` array does not cross the HTTP boundary — so this is the only place they can be
+     recovered from, and the summary needs them to be honest about what was skipped. */
+  if (evt.message.startsWith("⚠")) {
+    record.warnings.push(evt.message.replace(/^⚠\s*/, ""));
+  }
+}
+
+/**
+ * Close a run.
+ *
+ * @param {string} id
+ * @param {{ status: Exclude<ImportRunRecord["status"], "running">; error?: string }} outcome
+ */
+export function finishImportRun(
+  id: string,
+  outcome: { status: Exclude<ImportRunRecord["status"], "running">; error?: string },
+): void {
+  const record = runs.records.find((r) => r.id === id);
+  if (record) {
+    record.status = outcome.status;
+    record.error = outcome.error ?? "";
+  }
+  controller = null;
+}
+
+/**
+ * The record for one tool call, or null. Reactive — read it inside an `effect()` to repaint on it.
+ *
+ * @param {string} id
+ * @returns {ImportRunRecord | null}
+ */
+export function importRun(id: string): ImportRunRecord | null {
+  return runs.records.find((r) => r.id === id) ?? null;
+}
+
+/** The run still going, or null. What the panel's watcher tracks. */
+export function activeImportRun(): ImportRunRecord | null {
+  return runs.records.find((r) => r.status === "running") ?? null;
+}
+
+/** Abort the in-flight run. Called from `assistant.stop`, which cannot reach the tool directly. */
+export function abortImportRun(): void {
+  controller?.abort();
+  controller = null;
+}
+
+/** Drop every record. For New Chat and for tests. */
+export function resetImportRuns(): void {
+  abortImportRun();
+  runs.records.length = 0;
+}

package/src/services/import-seed.ts

@@ -0,0 +1,120 @@
+/**
+ * Import-seed.ts — the New Project Import form's hand-off to the assistant.
+ *
+ * The wizard collects a URL, crawl options, a model and a brief, then closes; the assistant takes
+ * the turn and runs the import as a tool call. This holds what the form gathered for the one turn
+ * that consumes it.
+ *
+ * **Module state, and deliberately NOT a copy of `agent-seed.ts`.** That one uses localStorage keyed
+ * by project root because the project it seeds opens in a NEW WINDOW, and the key is the
+ * cross-window channel. Neither half of that applies here: the project does not exist yet at
+ * hand-off time, so there is no root to key on, and the assistant taking the turn is in this window
+ * — `import_site` is `no-project` tiered precisely because it runs before there is a project. A
+ * localStorage clone would be a channel with nothing on the other end and a key that cannot be
+ * computed.
+ *
+ * @license MIT
+ */
+
+import type { ImportBreakpointPolicy } from "../types";
+
+/** What the wizard gathered, as the tool needs it. */
+export interface ImportBrief {
+  /** Absolute http(s) URL of the site to clone. */
+  url: string;
+  /** Human project name (the wizard prefills it from the hostname). */
+  name: string;
+  /** Absolute destination directory, already resolved from Location + folder name. */
+  directory: string;
+  depth: number;
+  maxPages: number;
+  /**
+   * How many of the site's declared breakpoints the project keeps.
+   *
+   * A real site declares as many as it has accumulated frameworks — nine is ordinary — and each one
+   * is a canvas size in Studio and a column in every style editor. The wizard defaults this to
+   * three because that is the complaint it answers, not because three is a magic number.
+   */
+  breakpoints: ImportBreakpointPolicy;
+  aiComponents: boolean;
+  /** Build and screenshot-diff the result. Off by default — it roughly doubles the run. */
+  verify: boolean;
+  /**
+   * The average fidelity, 0..100, the clone has to reach for `verify` to report success.
+   *
+   * Only meaningful when `verify` is on. A finding rather than a failure here: the project is
+   * written and opened either way, and the assistant says the bar was missed.
+   */
+  minFidelity: number;
+  /** Empty means "whatever the assistant would use" (`preferredModel()`). */
+  model: string;
+  /** What the user wants done with the site once it is cloned. May be empty. */
+  prompt: string;
+}
+
+let _brief: ImportBrief | null = null;
+
+/**
+ * Store the brief the assistant's next turn will act on.
+ *
+ * @param {ImportBrief} brief
+ */
+export function setPendingImportBrief(brief: ImportBrief): void {
+  _brief = brief;
+}
+
+/**
+ * The brief without consuming it — what `import_site` reads to fill in a destination the model was
+ * never told and must not invent.
+ *
+ * @returns {ImportBrief | null}
+ */
+export function pendingImportBrief(): ImportBrief | null {
+  return _brief;
+}
+
+/**
+ * Forget the brief.
+ *
+ * There is deliberately no consume-on-read here, unlike `agent-seed.ts`. TWO readers need the same
+ * brief and they read at different moments: the panel, to compose the turn, and `import_site`, for
+ * the destination — which is minutes later, after the model has decided to call it. A read that
+ * cleared would leave the tool inventing a path the user never chose. The tool clears it once the
+ * import has actually run.
+ */
+export function clearPendingImportBrief(): void {
+  _brief = null;
+}
+
+// ─── The hand-off itself ────────────────────────────────────────────────────
+
+/**
+ * The assistant's side of the hand-off, registered at boot.
+ *
+ * A late-bound slot for the same reason `services/project-adoption.ts` is one: the New Project
+ * wizard must not import `panels/ai-panel.ts`. That import is not just a layering preference — the
+ * panel constructs a `DocumentAssistant` singleton at module load, so reaching for it from
+ * `new-project/` drags a live assistant into every surface that opens the wizard.
+ */
+let _handoff: ((brief: ImportBrief) => Promise<void>) | null = null;
+
+/**
+ * Register the assistant's hand-off (studio.ts boot).
+ *
+ * @param {(brief: ImportBrief) => Promise<void>} fn
+ */
+export function setImportHandoff(fn: (brief: ImportBrief) => Promise<void>): void {
+  _handoff = fn;
+}
+
+/**
+ * Start the import as an assistant turn.
+ *
+ * A no-op with nothing registered — a reduced host (a test fixture, an embedder without the
+ * assistant) would otherwise crash on a button the wizard should simply not have offered.
+ *
+ * @param {ImportBrief} brief
+ */
+export async function runImportHandoff(brief: ImportBrief): Promise<void> {
+  await _handoff?.(brief);
+}

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

@@ -127,6 +127,23 @@ export const SETTINGS = {
     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",