@jxsuite/studio 6.1.1 → 8.0.0

package/src/services/ai-project-tools.ts

@@ -15,9 +15,10 @@
  */
 
 import { createToolDefinition } from "@jxsuite/ai/tools";
-import type { CreateProjectDestination } from "../types";
+import { isJsonObject, isNumber } from "@jxsuite/schema/guards";
+import type { CreateProjectDestination, StudioPlatform } from "../types";
 import type { ToolRegistry } from "@jxsuite/ai/tools";
-import type { JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
+import type { JsonValue, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 import { getPlatform } from "../platform";
 import { workspace } from "../workspace/workspace";
 import { projectState } from "../store";
@@ -26,6 +27,7 @@ import { adoptCreatedProject } from "./project-adoption";
 import { translateValidationError } from "./ai-tools";
 import { validateDoc, validateProjectConfig } from "./jx-validate";
 import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
+import type { CandidateDocument } from "./ai-write-report";
 import { invalidPathResult, normalizeRelPath } from "./project-path";
 
 /** Directories the file tools never descend into or report. */
@@ -50,21 +52,26 @@ function isJxDocPath(path: string): boolean {
 }
 
 /** Structural sniff for Jx-document-shaped JSON values. */
-function looksLikeJxDoc(value: unknown): boolean {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    !Array.isArray(value) &&
-    ("tagName" in value || "$id" in value || "$elements" in value)
-  );
+function looksLikeJxDoc(value: JsonValue): boolean {
+  return isJsonObject(value) && ("tagName" in value || "$id" in value || "$elements" in value);
+}
+
+/** One row of `list_files`'s answer. `size` is omitted when the platform reports none. */
+interface ListedEntry {
+  path: string;
+  type: string;
+  size?: number;
 }
 
 export interface ProjectToolsCtx {
   getTab: () => Tab | null;
-  validate?: (doc: unknown) => Promise<string[]>;
-  /** Gate for `project.json` writes — the per-project entry document, not the document schema. */
-  validateProject?: (config: unknown) => Promise<string[]>;
-  renderCheck?: (doc: unknown) => Promise<{ ok: true } | { ok: false; error: string }>;
+  validate?: (doc: CandidateDocument) => Promise<string[]>;
+  /**
+   * Gate for `project.json` writes — the per-project entry document, not the document schema. It
+   * judges the live configuration and a candidate parsed from the model's text alike.
+   */
+  validateProject?: (config: ProjectConfig | JsonValue) => Promise<string[]>;
+  renderCheck?: (doc: CandidateDocument) => Promise<{ ok: true } | { ok: false; error: string }>;
   /** Live getter — the project style appears only after a project is open/bootstrapped. */
   getProjectStyle?: () => Record<string, string> | undefined;
   /** The open tab whose `documentPath` equals the given project-relative path, if any. */
@@ -139,13 +146,15 @@ export function registerProjectTools(
         required: [],
       },
       async execute(args) {
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed, which refuses
+           a `dir` that is present but not a string. */
         const { dir } = args as { dir?: string };
         const start = dir === undefined || dir === "" ? "." : normalizeRelPath(dir);
         if (start === null) {
           return invalidPathResult(dir);
         }
         const platform = getPlatform();
-        const entries: { path: string; type: string; size?: number }[] = [];
+        const entries: ListedEntry[] = [];
         const queue = [start];
         let truncated = false;
         while (queue.length > 0 && !truncated) {
@@ -166,11 +175,11 @@ export function registerProjectTools(
               truncated = true;
               break;
             }
-            entries.push({
-              path,
-              type: e.type,
-              ...(typeof e.size === "number" ? { size: e.size } : {}),
-            });
+            const entry: ListedEntry = { path, type: e.type };
+            if (isNumber(e.size)) {
+              entry.size = e.size;
+            }
+            entries.push(entry);
             if (e.type === "directory") {
               queue.push(path);
             }
@@ -204,9 +213,12 @@ export function registerProjectTools(
         required: ["path"],
       },
       async execute(args) {
-        const relPath = normalizeRelPath((args as { path: string }).path);
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed, so the
+           required `path` is present and a string. */
+        const { path } = args as { path: string };
+        const relPath = normalizeRelPath(path);
         if (relPath === null) {
-          return invalidPathResult((args as { path: string }).path);
+          return invalidPathResult(path);
         }
         try {
           const content = await getPlatform().readFile(relPath);
@@ -255,6 +267,8 @@ export function registerProjectTools(
         required: ["path", "content"],
       },
       async execute(args, ctx) {
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed, so the required
+           `path` and `content` are both present and strings. */
         const { path, content } = args as { path: string; content: string };
         const relPath = normalizeRelPath(path);
         if (relPath === null) {
@@ -279,11 +293,12 @@ export function registerProjectTools(
         }
 
         // Pre-validate Jx documents — disk writes have no undo to lean on.
-        let parsed: unknown;
+        let parsed: JsonValue | undefined;
         const isJson = relPath.endsWith(".json") && relPath !== "project.json";
         if (isJson) {
           try {
-            parsed = JSON.parse(content);
+            // SAFETY: `JSON.parse` without a reviver yields nothing but JSON values.
+            parsed = JSON.parse(content) as JsonValue;
           } catch (error) {
             return {
               success: false,
@@ -292,7 +307,8 @@ export function registerProjectTools(
           }
         }
         let tokenHints = "";
-        if (isJson && (isJxDocPath(relPath) || looksLikeJxDoc(parsed))) {
+        // The parse above sets `parsed` exactly when `isJson` holds: it never yields `undefined`.
+        if (parsed !== undefined && (isJxDocPath(relPath) || looksLikeJxDoc(parsed))) {
           const errors = await validate(parsed);
           if (errors.length > 0) {
             const formatted = errors.map((e) => `- ${translateValidationError(e)}`).join("\n");
@@ -313,6 +329,9 @@ export function registerProjectTools(
           const projectStyle = getProjectStyle?.();
           if (projectStyle) {
             tokenHints = formatTokenHints(
+              /* SAFETY: `flagHardcodedTokens` re-checks every member it reads — object-ness, each
+                 `style` value as a string, `children` as an array — so a JSON value that is not
+                 quite a node is read defensively; its parameter type names the intended input. */
               flagHardcodedTokens(parsed as JxMutableNode, projectStyle),
             );
           }
@@ -322,9 +341,10 @@ export function registerProjectTools(
            model-authored text, and the gate below is the whole reason we do not trust its shape. */
         let projectConfig: ProjectConfig | undefined;
         if (relPath === "project.json") {
-          let parsedConfig: unknown;
+          let parsedConfig: JsonValue;
           try {
-            parsedConfig = JSON.parse(content);
+            // SAFETY: `JSON.parse` without a reviver yields nothing but JSON values.
+            parsedConfig = JSON.parse(content) as JsonValue;
           } catch (error) {
             return {
               success: false,
@@ -353,7 +373,9 @@ export function registerProjectTools(
               error: `project.json has schema errors — nothing was written. Fix these and retry:\n${formatted}`,
             };
           }
-          // Narrowed only now: the assertion is earned by the schema gate, not by JSON.parse.
+          /* SAFETY: narrowed only now, because the assertion is earned by the schema gate rather
+             than by `JSON.parse`: the per-project entry schema found no violation this text did not
+             already have on disk. */
           projectConfig = parsedConfig as ProjectConfig;
         }
 
@@ -416,6 +438,9 @@ export function registerProjectTools(
         required: ["query"],
       },
       async execute(args) {
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `query` is a
+           present string and `extensions`, when present, an array. Its items are not checked here;
+           the platform's search receives them as given. */
         const { query, extensions } = args as { query: string; extensions?: string[] };
         try {
           const results = await getPlatform().searchFiles(query, extensions);
@@ -490,6 +515,10 @@ export function registerProjectTools(
         required: ["name"],
       },
       async execute(args, ctx) {
+        /* SAFETY: a strict tool runs only after the registry's `validate()` passed: `name` is a
+           present string, the optional strings and `private` have their declared types when
+           present, and `design` is an object. Its colour and font members are not checked here;
+           the platform's scaffold receives them as given. */
         const {
           name,
           description,
@@ -562,14 +591,21 @@ export function registerProjectTools(
 
         let result: { root: string; config: object };
         try {
-          result = await platform.createProject({
+          const request: Parameters<StudioPlatform["createProject"]>[0] = {
             name,
             destination,
             directory: slug,
-            ...(description ? { description } : {}),
-            ...(template ? { template } : {}),
-            ...(design ? { design } : {}),
-          });
+          };
+          if (description) {
+            request.description = description;
+          }
+          if (template) {
+            request.template = template;
+          }
+          if (design) {
+            request.design = design;
+          }
+          result = await platform.createProject(request);
         } catch (error) {
           return {
             success: false,

package/src/services/ai-session-store.ts

@@ -2,13 +2,13 @@
 /**
  * Ai-session-store.js — project-scoped multi-session chat history in localStorage.
  *
- * Pure storage CRUD for the assistant's conversations: a small index of session
- * metadata plus one payload key per session, so per-send writes touch a single
- * conversation. No reactivity and no chat-state knowledge — document-assistant
- * owns the live session; this module only loads/saves plain message arrays.
+ * Pure storage CRUD for the assistant's conversations: a small index of session metadata plus one
+ * payload key per session, so per-send writes touch a single conversation. No reactivity and no
+ * chat-state knowledge — document-assistant owns the live session; this module only loads/saves
+ * plain message arrays.
  *
- * Cross-window note: multiple studio windows share these keys; index writes are
- * last-write-wins, which is accepted for chat history.
+ * Cross-window note: multiple studio windows share these keys; index writes are last-write-wins,
+ * which is accepted for chat history.
  *
  * @license MIT
  */
@@ -73,18 +73,27 @@ function legacyKey(root: string) {
 
 // ─── Storage helpers (defensive: quota/unavailable/corrupt → absent) ────────
 
+/** `localStorage`, or `undefined` on a host that has none (a worker, a test run without a DOM). */
+function storage(): Storage | undefined {
+  return typeof localStorage === "undefined" ? undefined : localStorage;
+}
+
 function readJson<T>(key: string): T | null {
   try {
-    const raw = globalThis.localStorage?.getItem(key);
+    const raw = storage()?.getItem(key);
+    /* SAFETY: every key this module reads is one it wrote through `writeJson`, with the shape its
+       reader names (an index is a `SessionIndex`, a payload or legacy key a `PersistedMessage[]`).
+       A value that is not — corrupt, or written by a foreign build — is caught by each reader's
+       `Array.isArray` check before any member is used. */
     return raw ? (JSON.parse(raw) as T) : null;
   } catch {
     return null;
   }
 }
 
-function writeJson(key: string, value: unknown) {
+function writeJson(key: string, value: SessionIndex | PersistedMessage[]) {
   try {
-    globalThis.localStorage?.setItem(key, JSON.stringify(value));
+    storage()?.setItem(key, JSON.stringify(value));
   } catch {
     // Storage full or unavailable — chat history is not critical.
   }
@@ -92,7 +101,7 @@ function writeJson(key: string, value: unknown) {
 
 function removeKey(key: string) {
   try {
-    globalThis.localStorage?.removeItem(key);
+    storage()?.removeItem(key);
   } catch {
     /* Ignore */
   }

package/src/services/ai-system-prompt.ts

@@ -10,7 +10,8 @@
 import { VOID_ELEMENTS } from "../store.js";
 import { flattenTree } from "../state.js";
 import type { ComponentEntry } from "../files/components.js";
-import type { JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
+import { isBoolean, isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JsonPrimitive, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 
 /** Options for {@link buildSystemPrompt}. */
 interface BuildSystemPromptOptions {
@@ -362,7 +363,7 @@ ${[...VOID_ELEMENTS].join(", ")}
 
 // ─── State Shape Decision Tree ───────────────────────────────────────────────
 
-const STATE_SHAPE_DECISION_TREE = `## State Shape Decision Tree
+const STATE_ENTRY_DECISION_TREE = `## State Shape Decision Tree
 
 When adding state to a component, choose the right shape:
 
@@ -712,7 +713,7 @@ export const SYSTEM_PROMPT_STATIC_PREFIX =
     // 2. Jx schema reference — kept in ALL modes (pre-project the model plans starter content)
     JX_SCHEMA_REFERENCE,
     // 2a. State shape decision tree
-    STATE_SHAPE_DECISION_TREE,
+    STATE_ENTRY_DECISION_TREE,
     // 2b. Real-world patterns
     REAL_WORLD_PATTERNS,
     // 2c. Design principles — spacing, type, color, layout, restraint
@@ -756,9 +757,9 @@ export function buildSystemPrompt({
   // Their records' own gates, for the same reason — one function answers both the prompt and the
   // Executor (`advertisedCommandTools`).
   const toolList = [
-    ...AI_TOOL_TIERS.filter((t) =>
-      toolActive(t, { canImport, hasDocument, hasProject, treeEditable }),
-    ).map((t) => t.blurb),
+    ...AI_TOOL_TIERS.flatMap((t) =>
+      toolActive(t, { canImport, hasDocument, hasProject, treeEditable }) ? [t.blurb] : [],
+    ),
     ...commandTools,
   ]
     .map((blurb) => `- ${blurb}`)
@@ -860,6 +861,9 @@ function buildDocumentSummary(doc: JxMutableNode) {
   lines.push(`\nElement tree (${flat.length} nodes):`);
   for (const item of flat) {
     const indent = "  ".repeat(item.depth);
+    /* SAFETY: both added members are optional, so the assertion claims nothing a row must carry;
+       one that lacks them reads `undefined`. `FlatRow` itself declares neither, so this label
+       currently prints as `undefined` for every row, a known defect rather than a contract. */
     const row = item as typeof item & { id?: string; tag?: string };
     const label = row.id || row.tag;
     lines.push(`${indent}${label}`);
@@ -872,19 +876,16 @@ function buildDocumentSummary(doc: JxMutableNode) {
       lines.push(`\nState keys (${stateKeys.length}): ${stateKeys.join(", ")}`);
       // Add type info for each state entry
       for (const key of stateKeys) {
-        const entry: unknown = doc.state[key];
-        const entryObj = entry as Record<string, unknown>;
+        const entry = doc.state[key];
         let typeStr = "unknown";
-        if (!entry || typeof entry !== "object") {
-          typeStr = typeof entry;
-        } else if (entryObj.$prototype === "Function") {
+        if (!isNonNullObject(entry)) {
+          typeStr = primitiveTypeName(entry);
+        } else if ("$prototype" in entry && entry.$prototype === "Function") {
           typeStr = "Function";
-        } else if (entryObj.$prototype === "Data") {
+        } else if ("$prototype" in entry && entry.$prototype === "Data") {
           typeStr = "Data source";
-        } else if (typeof entry === "string" && (entry as string).includes("${")) {
-          typeStr = "Computed";
-        } else if (entryObj.type) {
-          typeStr = `Typed (${entryObj.type})`;
+        } else if ("type" in entry && entry.type) {
+          typeStr = `Typed (${String(entry.type)})`;
         } else {
           typeStr = "Scalar";
         }
@@ -895,15 +896,32 @@ function buildDocumentSummary(doc: JxMutableNode) {
 
   // Imported elements
   if (doc.$elements && doc.$elements.length > 0) {
-    const refs = doc.$elements
-      .map((e) => (typeof e === "string" ? e : e.$ref || "(unknown)"))
-      .join(", ");
+    const refs = doc.$elements.map((e) => (isString(e) ? e : e.$ref || "(unknown)")).join(", ");
     lines.push(`\nImported elements: ${refs}`);
   }
 
   return lines.join("\n");
 }
 
+/**
+ * `typeof` of a state entry that is not an object, spelled as the summary has always printed it.
+ *
+ * @param {JsonPrimitive | undefined} value
+ * @returns {string}
+ */
+function primitiveTypeName(value: JsonPrimitive | undefined): string {
+  if (isString(value)) {
+    return "string";
+  }
+  if (isNumber(value)) {
+    return "number";
+  }
+  if (isBoolean(value)) {
+    return "boolean";
+  }
+  return value === null ? "object" : "undefined";
+}
+
 /**
  * Build a project context summary.
  *
@@ -937,6 +955,9 @@ function buildProjectSummary({
   if (components && components.length > 0) {
     lines.push(`Available components (reuse these instead of rebuilding):`);
     for (const c of components) {
+      /* SAFETY: both added members are optional, so the assertion claims nothing an entry must
+         carry: a discovered component may still bring a legacy `tag` or `name`, and one without
+         them reads `undefined` and falls through to `path`. */
       const entry = c as ComponentEntry & { tag?: string; name?: string };
       const tag = entry.tagName || entry.tag || entry.name || entry.path;
       const label = c.$id ? ` — ${c.$id}` : "";
@@ -952,7 +973,12 @@ function buildProjectSummary({
         `Design tokens (always use var(--token) — never hard-code a color, radius, or font that a token defines):`,
       );
       type TokenEntry = (typeof tokens)[number];
-      const groups: { color: TokenEntry[]; font: TokenEntry[]; other: TokenEntry[] } = {
+      interface TokenGroups {
+        color: TokenEntry[];
+        font: TokenEntry[];
+        other: TokenEntry[];
+      }
+      const groups: TokenGroups = {
         color: [],
         font: [],
         other: [],