@jxsuite/studio 4.1.0 → 5.1.0

package/src/commands/registry.ts

@@ -8,13 +8,17 @@
  * becomes a RENDERING of these records. A surface may choose whether to show a command; it may
  * never decide what it is called, when it is available, or what it does (plan §2, principle 1).
  *
- * Three things fail loudly at registration rather than degrading into a surface disagreement:
+ * Four things fail loudly at registration rather than degrading into a surface disagreement:
  *
  * - A duplicate id — the second definition site the whole design exists to prevent;
  * - A chord already claimed in the same `keyScope` (see `keymap.ts`) — this is exactly how ⌘W came to
  *   disagree with the tab strip's × button;
  * - A `menus` placement the level × placement matrix does not admit (see `levels.ts`), so a
- *   selection-level verb cannot appear in the Command Bar even in a hand-written test app.
+ *   selection-level verb cannot appear in the Command Bar even in a hand-written test app;
+ * - An `aiTool` projection that cannot be completed (see {@link AiToolProjection}): a name that is
+ *   not snake_case or is already another record's, a projection with no `report`, an
+ *   application-level record, a selection-level record that declares the `paths` the bridge
+ *   supplies, or a gated record with no `requires` sentence for the model to act on.
  *
  * `when` / `enablement` are `(ctx) => boolean` closures, modelled on the shipped
  * `services/gated-registry.ts` `ToolAvailability`, and `requires` is ONE string with three
@@ -23,13 +27,17 @@
  *
  * The registry takes its context by injection (`getContext`), so nothing here imports a state
  * module. That is what lets the CI checks import the command set in a bare Bun process and lets
- * every test build the exact state it wants to assert against.
+ * every test build the exact state it wants to assert against. The one store it reaches is the
+ * notification store, through `run-reported.ts`, and only from `handleKeyEvent`: a chord's refusal
+ * has no caller to hand it to, so the registry files it where every other surface's refusal goes.
  */
 
 import { createKeymap } from "./keymap";
 import type { KeyChordEvent, Keymap, KeymapMatch } from "./keymap";
 import { checkRecordPlacements } from "./levels";
 import type { Category, KeyScope, Level, Placement } from "./levels";
+import { coerceArgs } from "./command-args";
+import { runReported } from "./run-reported";
 import type { CommandContext } from "./context";
 
 /** Arguments as they arrive from a palette prompt, an automation manifest step or an AI tool call. */
@@ -64,19 +72,87 @@ export interface Command<A = void> {
   requires?: string;
   /** Default chord(s), e.g. `"mod+shift+p"`. User overrides layer on top. */
   keybinding?: string | readonly string[];
-  /** JSON Schema for {@link Command.run}'s args — the palette's prompt AND the AI tool's params. */
+  /**
+   * JSON Schema for {@link Command.run}'s args — the palette's prompt, the AI tool's params, the
+   * shot check's contract AND what {@link CommandRegistry.run} coerces the received record against
+   * before `run` sees it (`command-args.ts`'s `coerceArgs`). One object, four readers.
+   */
   args?: object;
   /** Surfaces this command renders in. Defaults to `["palette"]`. */
   menus?: readonly Placement[];
   /** Menu ordering key: "1_clipboard", "3_structure", "9_danger". */
   group?: string;
+  /**
+   * How the effect is undone. Also the LEDGER SCOPE of a bridged write:
+   * `services/ai-command-tools.ts` records one "Changed N files" entry per path a projected run
+   * touched, and it reads this field to know whether there was a write at all and whether ⌘Z can
+   * reach it. A record that writes and forgets `undo` is invisible to the ledger.
+   */
   undo?: UndoScope;
   destructive?: boolean;
-  /** Opt-in projection to the assistant. The human's gate and the agent's gate stay one predicate. */
-  aiTool?: { name: string; description: string };
+  /**
+   * Opt-in projection to the assistant. DECLARING IT MAKES A TOOL — see {@link AiToolProjection}.
+   * The human's gate and the agent's gate stay one predicate because the tool IS `run`.
+   */
+  aiTool?: AiToolProjection<A>;
   run: (ctx: CommandContext, args: A) => void | Promise<void>;
 }
 
+/** What a projected command tells the model after `run` resolved. A string is a summary alone. */
+export interface AiToolReport {
+  /** ONE sentence describing the state the person now sees. Never "it worked". */
+  summary: string;
+  /** Structured facts the model can act on (a findings list). Reaches it as `ToolResult.data`. */
+  data?: unknown;
+  /**
+   * Files this run changed, for the "Changed N files" ledger. Defaults from {@link Command.undo}:
+   * `"document"` is the active document's path, `"project"` is `project.json`. A record with `undo:
+   * "none"` MUST return it: a disk write with no path is exactly what the ledger exists to name,
+   * and `tests/ai-command-tools.test.ts` holds every kept `undo: "none"` projection to it. An
+   * idempotent verb whose run found the state it was asked for and wrote nothing returns `[]`, and
+   * the ledger files nothing: the default is "what this record writes", not "what this run wrote",
+   * and only the record can tell the two apart.
+   */
+  wrote?: readonly string[];
+}
+
+/**
+ * Opt-in projection to the assistant. Declaring it MAKES a tool: `services/ai-command-tools.ts`
+ * lists one per record that carries it, `execute` is `registry.run(id)`, `parameters` is the
+ * record's own `args` object, and the tool is advertised exactly while `isEnabled(id)` holds (a
+ * selection-level record composes through `selection.setPaths`, so its tool takes `paths` and is
+ * advertised while a canvas document is open). Nothing else about the tool is written anywhere, so
+ * nothing can forget to write it — issue 273 was forty-seven declarations that reached the
+ * assistant from none of them, because each waited on a hand-registered tool nobody wrote.
+ *
+ * A projection without a `report` does not compile. `run` returns void, and a tool that can only
+ * say "done" is one the model builds its next three edits on blind.
+ *
+ * @template A The argument record `run` receives — `report` reads the same one.
+ */
+export interface AiToolProjection<A = void> {
+  /** Snake_case; unique across records AND the hand-registered tools (both asserted). */
+  name: string;
+  /**
+   * The one description. The prompt blurb is derived from it (`name(params) — description`), and
+   * the bridge appends the undo scope and the destructive flag, so say neither here.
+   */
+  description: string;
+  /**
+   * Called after `run` resolved. `before` is the context the verb ran against (for a selection
+   * verb: after the selector step), `after` is the context now. May close over module state, as
+   * `enablement` closures already do; never over injected deps, because the view reads the LIVE
+   * record and `appCommandSet()`'s no-op instances are what the tests read. Refusals are `run`'s
+   * job (throw); `report` only describes. One that throws anyway is answered as a failure that says
+   * the run happened, with the ledger filed from `undo`'s defaults — never as a refusal.
+   */
+  report: (facts: {
+    before: CommandContext;
+    after: CommandContext;
+    args: A;
+  }) => string | AiToolReport;
+}
+
 /**
  * A command of unknown argument type, as stored.
  *
@@ -88,6 +164,13 @@ export type AnyCommand = Command<never>;
 /** `<namespace>.<verb>`, lowercase namespace, at least two dot-separated segments. */
 const ID_PATTERN = /^[a-z][a-z\d]*(\.[a-zA-Z\d]+)+$/;
 
+/**
+ * `snake_case`, the wire shape every function-calling API accepts unquoted. A tool name is what the
+ * model TYPES, so a projection named `deleteNode` or `delete-node` is refused here rather than
+ * discovered as a model that keeps misspelling it.
+ */
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+
 /** Thrown when a command is invoked while its own predicate refuses it. */
 export class CommandUnavailableError extends Error {
   readonly commandId: string;
@@ -128,7 +211,11 @@ export interface CommandRegistry {
   disabledReason: (id: string) => string | undefined;
   /** The full refusal sentence, for an agent or a tooltip. `undefined` when the command is usable. */
   refusalMessage: (id: string) => string | undefined;
-  /** Run a command. Throws on an unknown id, or {@link CommandUnavailableError} when refused. */
+  /**
+   * Run a command. Throws on an unknown id, {@link CommandUnavailableError} when refused, or a
+   * `RangeError` naming the argument when `args` does not fit the record's schema — synchronously,
+   * before `run` is entered, whichever surface the call came from.
+   */
   run: (id: string, args?: CommandArgs) => void | Promise<void>;
   /** The chord index, conflict-checked at registration. */
   keymap: Keymap;
@@ -145,6 +232,60 @@ export interface CommandRegistryOptions {
   mac?: boolean;
 }
 
+/**
+ * Refuse an `aiTool` declaration that cannot be completed into a tool.
+ *
+ * Each is a thrown `Error` naming the record, in the idiom of the id/title/placement checks above
+ * it, because the alternative is the failure issue 273 catalogued: a declaration that reaches the
+ * model as a tool it cannot use, or does not reach it at all. `report` is required by the TYPE as
+ * well; the runtime check is for the JS caller `tsc` cannot stop.
+ */
+function checkProjection(command: AnyCommand, toolNames: ReadonlyMap<string, string>): void {
+  const tool = command.aiTool;
+  if (!tool) {
+    return;
+  }
+  if (!TOOL_NAME_PATTERN.test(tool.name)) {
+    throw new Error(`command "${command.id}" aiTool name "${tool.name}" is not snake_case`);
+  }
+  const claimant = toolNames.get(tool.name);
+  if (claimant !== undefined) {
+    throw new Error(
+      `command "${command.id}" aiTool name "${tool.name}" is already projected by "${claimant}"`,
+    );
+  }
+  if (typeof tool.report !== "function") {
+    throw new TypeError(
+      `command "${command.id}" declares aiTool without a report: a tool that can only say ` +
+        `"done" is refused`,
+    );
+  }
+  if (command.level === "application") {
+    throw new Error(
+      `command "${command.id}" is application-level and cannot project to the assistant: an ` +
+        `application verb acts on the editor, which the model cannot see`,
+    );
+  }
+  /* The bridge composes a selection-level verb through `selection.setPaths` and merges the
+     selector's `paths` property in FRONT of the record's own `args`, so a record that declares its
+     own `paths` would have two definitions of one argument — the model would read the record's
+     description and the bridge would hand the value to the selector. */
+  const properties = (command.args as { properties?: Record<string, unknown> } | undefined)
+    ?.properties;
+  if (command.level === "selection" && properties && Object.hasOwn(properties, "paths")) {
+    throw new Error(
+      `command "${command.id}" is selection-level and may not declare "paths": the assistant ` +
+        `supplies it`,
+    );
+  }
+  if ((command.when || command.enablement) && !command.requires) {
+    throw new Error(
+      `command "${command.id}" projects to the assistant but has no requires sentence; ` +
+        `"${GENERIC_REQUIREMENT}" is not a refusal a model can act on`,
+    );
+  }
+}
+
 /**
  * Build an empty registry.
  *
@@ -154,6 +295,8 @@ export interface CommandRegistryOptions {
 export function createCommandRegistry(options: CommandRegistryOptions): CommandRegistry {
   const commands = new Map<string, AnyCommand>();
   const keymap = createKeymap(options.mac === undefined ? {} : { mac: options.mac });
+  /** Projected tool name → the id that claimed it. A second claimant is refused by name. */
+  const toolNames = new Map<string, string>();
 
   function mustGet(id: string): AnyCommand {
     const command = commands.get(id);
@@ -198,10 +341,14 @@ export function createCommandRegistry(options: CommandRegistryOptions): CommandR
       if (violations.length > 0) {
         throw new Error(`command "${command.id}" ${violations[0]!.message}`);
       }
+      checkProjection(command as AnyCommand, toolNames);
       // Chord conflicts throw from the keymap; do this LAST so a rejected record leaves the
-      // Registry untouched in every failure mode.
+      // Registry untouched in every failure mode — the tool name is claimed only after it.
       keymap.add(command);
       commands.set(command.id, command as AnyCommand);
+      if (command.aiTool) {
+        toolNames.set(command.aiTool.name, command.id);
+      }
     },
     registerAll(list) {
       for (const command of list) {
@@ -250,7 +397,14 @@ export function createCommandRegistry(options: CommandRegistryOptions): CommandR
       if (!enabledWith(command, ctx)) {
         throw new CommandUnavailableError(id, command.requires ?? GENERIC_REQUIREMENT);
       }
-      return command.run(ctx, args as never);
+      /* Availability first, argument second. The schema is coerced HERE, once, for every caller —
+         the palette, `__jxAutomation`, the assistant's tool and a chord — rather than inside each
+         `run` body, so a caller that passes a value the record does not declare is refused with the
+         sentence the palette would show before the implementation is entered. The `run` bodies keep
+         their typed readers; `coerceArgs` dispatches to the same functions, so the two cannot
+         disagree. A record with no `args` takes whatever it was handed, as it always has. */
+      const coerced = command.args ? coerceArgs(id, command.args, args) : args;
+      return command.run(ctx, coerced as never);
     },
     keymap,
     handleKeyEvent(event, scopeStack) {
@@ -284,7 +438,20 @@ export function createCommandRegistry(options: CommandRegistryOptions): CommandR
       if (!registry.isEnabled(hit.commandId)) {
         return hit.commandId;
       }
-      void registry.run(hit.commandId);
+      /* An ARGUMENT refusal is the one refusal that can still happen here, and it is REPORTED
+         rather than thrown. A chord runs its record with `{}`, and `run` coerces that against the
+         schema first, so a record whose schema requires a key cannot be a chord — every shipped
+         keybinding is held to `required: []` by the sweep in `tests/command-args.test.ts`, and a
+         user's own keymap override that binds one anyway hears about it as a Problems row naming
+         the command and the key, rather than as a chord that silently does nothing. It used to
+         leave as a `RangeError` out of the keydown listener, which named the same things to the
+         console and to nobody; `run-reported.ts` is what catches that shape, and the rejection a
+         `run` body may produce later, for every surface alike. A gate that closes BETWEEN the
+         `isEnabled` above and `run`'s own re-read is reported the same way, and that is a choice:
+         the silent claim above is for a chord the person can see is disabled, while a gate that
+         moved under the chord is state the person cannot see, and the `requires` sentence in
+         Problems is the one account of why nothing happened. */
+      void runReported(registry, hit.commandId, undefined, "Keyboard");
       return hit.commandId;
     },
     context: options.getContext,

package/src/commands/run-reported.ts

@@ -0,0 +1,120 @@
+/**
+ * Run-reported.ts — run a command from a surface, and let a refusal land in Problems.
+ *
+ * `registry.run` refuses in two shapes, and a caller that catches one and not the other still lets
+ * a refusal out. It throws SYNCHRONOUSLY — `CommandUnavailableError` when the gate refuses, a
+ * `RangeError` when `coerceArgs` refuses the received record BEFORE `run` is entered, and whatever
+ * a synchronous `run` body throws — and it REJECTS when an async `run` body does. A bare `void
+ * registry.run(id, args)` lets the first shape out of the click, keydown or notice action it came
+ * from, and a `.catch` on the promise alone catches nothing when `run` has already thrown; a
+ * `Promise.resolve(registry.run(...))` around it is the same mistake with more characters, because
+ * the argument is evaluated first. Three surfaces had grown the same six-line try/catch in reply
+ * (the palette's `runCommand`, the Settings menu's `runRow` and the Languages panel's `runByName`)
+ * while ten others still ran bare, which is the drift issue 333 names: a refusal reached Problems
+ * or the console depending on which surface the person happened to be on.
+ *
+ * This is the one spelling. It catches both shapes, files the sentence in Problems — the tier
+ * `notify.error` chooses, and the right one: a refusal names something the person has to fix or a
+ * schema that drifted from its caller, and neither is a toast that may be taken away — and returns
+ * a promise that never rejects, so a caller may `void` it or `await` it without a `.catch`.
+ *
+ * A refusal is the whole message; a CRASH is not. `CommandUnavailableError` and `RangeError` are
+ * the two shapes the registry and `coerceArgs` refuse with, and each is a sentence written to be
+ * read, so the Problems row is complete. Anything else out of a `run` body — a `TypeError` on a
+ * node that was not there — is a bug, and its stack is the part that matters; the row still names
+ * it, and the error object also goes to the console, where the palette used to send everything and
+ * where a trace can be opened. Without that the helper would have made every surface quieter than
+ * the keydown listener it replaced, which reached `window.onerror`.
+ *
+ * Two spellings, one rule. {@link runReported} takes the registry as a PARAMETER: `editor/
+ * shortcuts.ts`, the block action bar and the registry's own `handleKeyEvent` are handed theirs,
+ * and a helper that resolved the active registry for them would silently do nothing wherever a
+ * test, or a second window kind, ran a registry that is not the published one.
+ * {@link runActiveReported} is the same call for a surface that was spelled `void
+ * activeRegistry()?.run(id, args)` — a footer row, a palette hit, a tab-strip chip — and it keeps
+ * that spelling's one property: before the bootstrap has published a registry there is nothing to
+ * run and nothing to report, exactly as the `?.` was silent.
+ *
+ * The sweep in `tests/run-reported.test.ts` walks `packages/studio/src` for any other `.run(` on a
+ * registry. Two callers own their refusal and are named there as such — `services/automation.ts`
+ * and `services/ai-command-tools.ts`, where the script or the model is the one who reads it — and
+ * the `?.run(` spelling issue 333 did not list survives in a RATCHET of files the sweep names one
+ * by one, each still holding a bare call; the list can only shrink, so a new surface cannot spell
+ * it bare and an existing one converted must drop its entry.
+ *
+ * `runReported` does not pre-check `isEnabled`. A surface that renders a disabled control for a
+ * refused record has already shown the `requires` sentence, and a click that arrives on one anyway
+ * (state moved between the render and the click) is a refusal the person should read, not a
+ * swallowed no-op. The callers that DO pre-check keep doing so for their own reasons — a chord on a
+ * disabled command is claimed silently by `handleKeyEvent`, by design — and route what remains
+ * through here.
+ *
+ * @docs studio/interface/problems-and-progress
+ */
+
+import { errorMessage } from "@jxsuite/schema/parse";
+import { notify } from "../services/notify";
+import { activeRegistry } from "./active-registry";
+import type { CommandArgs, CommandRegistry } from "./registry";
+
+/**
+ * Whether an error is one of the two REFUSAL shapes, whose message is written to be read whole.
+ *
+ * By name rather than `instanceof CommandUnavailableError`: `registry.ts` imports this module for
+ * `handleKeyEvent`, and a value import back would close a cycle for one class whose constructor
+ * sets exactly this name. `RangeError` is the shape `coerceArgs` and a `run` body refuse with.
+ */
+function isRefusal(error: unknown): boolean {
+  return (
+    error instanceof RangeError ||
+    (error instanceof Error && error.name === "CommandUnavailableError")
+  );
+}
+
+/**
+ * Run `id` with `args` on `registry`, and file whatever refuses it in Problems under `source`.
+ *
+ * `source` is the SURFACE the run came from ("Palette", "Keyboard", "Languages"), the column the
+ * Problems panel groups by; it defaults to the command id, which is what the Settings menu filed
+ * under before this helper existed and is still a true answer to "who reported it". The Problems
+ * row is keyed by the command id, so a chord held down on a refusing record is one problem rather
+ * than sixty — the file-watcher rule `services/notify.ts` writes down for `key`.
+ *
+ * The returned promise settles when the command does, and never rejects: an `await` on it is a
+ * wait, not a second place the refusal could escape from.
+ */
+export function runReported(
+  registry: CommandRegistry,
+  id: string,
+  args?: CommandArgs,
+  source: string = id,
+): Promise<void> {
+  const report = (error: unknown) => {
+    if (!isRefusal(error)) {
+      // A crash, not a refusal: the row below carries the sentence, the console keeps the stack.
+      console.error(`${source}: command "${id}" failed`, error);
+    }
+    notify.error(errorMessage(error), { key: `command.run:${id}`, source });
+  };
+  let result: void | Promise<void>;
+  try {
+    result = registry.run(id, args);
+  } catch (error) {
+    report(error);
+    return Promise.resolve();
+  }
+  return Promise.resolve(result).catch(report);
+}
+
+/**
+ * {@link runReported} on this window's registry, or nothing before the bootstrap has published one.
+ *
+ * The `?.` this replaces was the surfaces' answer to `active-registry.ts` returning `null` for the
+ * frame before the bootstrap composes the registry; a click that lands in that frame has no
+ * registry to refuse it, so there is no refusal to file. The resolved promise keeps the caller's
+ * `void` honest either way.
+ */
+export function runActiveReported(id: string, args?: CommandArgs, source?: string): Promise<void> {
+  const registry = activeRegistry();
+  return registry ? runReported(registry, id, args, source) : Promise.resolve();
+}

package/src/content/entry-commands.ts

@@ -28,6 +28,7 @@ import {
 } from "../format/format-host";
 import { notify } from "../services/notify";
 import { activeTab } from "../workspace/workspace";
+import { serializeJson } from "../files/json-layout";
 import { invalidateReferenceEntries } from "../ui/form-controls";
 import { reloadDraftAwareGrids } from "../grid/sources/content-source";
 import { setIncludeDrafts } from "./draft-state";
@@ -63,7 +64,9 @@ async function seedText(collection: EntryCollection): Promise<string> {
     formatForPath(`untitled${collection.ext}`)?.name ??
     defaultContentFormat()?.name;
   if (collection.ext === ".json" || formatName === undefined) {
-    return JSON.stringify(seed, null, 2);
+    // The save serializer with no layout (`files/json-layout.ts`): a seed has no source text, and
+    // This is what the formatter makes of one, newline included.
+    return serializeJson(seed, null);
   }
   return formatSerialize(
     formatName,
@@ -187,12 +190,9 @@ export function contentCommands(): AnyCommand[] {
       when: (ctx) => ctx.project.open,
       enablement: () => creatableCollections().length > 0,
       undo: "project",
-      aiTool: {
-        description:
-          "Create a content entry in one of the project's collections, seeded from that " +
-          "collection's schema defaults, and open it in the entry form.",
-        name: "new_content_entry",
-      },
+      /* No `aiTool`, by §12.4's second deletion rule: `createEntry` awaits `createFileIn`, which
+         awaits the New File prompt for the name; a cancel resolves with nothing thrown. An optional
+         `name` argument that skips the prompt is the way back in, and is a UX call (issue 273). */
       run: async (_ctx, args) => {
         const names = creatableCollections();
         await createEntry(enumArg("content.newEntry", args, "collection", names));
@@ -210,12 +210,8 @@ export function contentCommands(): AnyCommand[] {
       group: "1_file",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description:
-          "Open a content entry as a schema-driven form — its collection's fields, with a picker " +
-          "for every reference to another collection.",
-        name: "open_entry_form",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface; the model has
+         `open_document`. */
       run: async (_ctx, args) => {
         await openEntryEditor(stringArg("content.openEntry", args, "path"));
       },
@@ -237,12 +233,12 @@ export function contentCommands(): AnyCommand[] {
       when: (ctx) => ctx.document.open,
       enablement: () => activeEntryTab() !== null,
       undo: "document",
-      aiTool: {
-        description:
-          "Mark the open content entry a draft, or published. Studio filters drafts out of its " +
-          "own lists; the build does not exclude them yet.",
-        name: "set_entry_draft",
-      },
+      /* No `aiTool`, by §12.4's fourth deletion rule: the draft flag is ONE FIELD on the entry,
+         and the model already writes fields — `set_property` at the root path for a JSON entry
+         (`mutateDocumentField` is the same `set-key` at `[]`), `write_file` for a frontmatter one.
+         The state is reachable — `open_document` opens a collection file as readily as
+         `content.openEntry` does — so the reason is redundancy, not reach. Six lines to re-enter
+         should a task want the flag by name rather than by key. */
       run: (_ctx, args) => {
         const tab = activeEntryTab();
         if (!tab) {
@@ -263,10 +259,7 @@ export function contentCommands(): AnyCommand[] {
       group: "2_view",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      aiTool: {
-        description: "Choose whether draft entries appear in Studio's content listings.",
-        name: "set_including_drafts",
-      },
+      /* No `aiTool`, by §12.4's first deletion rule: a listing filter for a person. */
       /*
        * Set the flag, then repaint what reads it.
        *