@jxsuite/studio 6.1.1 → 8.0.0

package/src/commands/command-args.ts

@@ -27,26 +27,55 @@
  * this — an id outside a declared set — and one refusal shape is easier to catch than two.
  */
 
+import { isBoolean, isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
+
+/**
+ * One received argument: a JSON value, or `undefined` for a key a caller left out. Every surface
+ * that sends arguments speaks JSON (a palette prompt, a manifest step, an AI tool call), and an
+ * explicit `undefined` is how a programmatic caller spells "absent" — JSON cannot carry one.
+ */
+export type CommandArgValue = JsonValue | undefined;
+
 /** Arguments as they arrive from a palette prompt, a manifest step or an AI tool call. */
-export type CommandArgValues = Record<string, unknown>;
+export type CommandArgValues = Record<string, CommandArgValue>;
 
 /** `command "<id>" argument "<key>": <problem>` — the one sentence shape every failure here uses. */
 function refuse(commandId: string, key: string, problem: string): RangeError {
   return new RangeError(`command "${commandId}" argument "${key}": ${problem}`);
 }
 
+/**
+ * The `typeof` word for a non-string JSON value, as every refusal sentence has always printed it:
+ * `null`, arrays and objects are all `object` to `typeof`, so they are all `object` here.
+ */
+function typeWordOf(value: JsonValue): string {
+  if (isNumber(value)) {
+    return "number";
+  }
+  if (isBoolean(value)) {
+    return "boolean";
+  }
+  return isString(value) ? "string" : "object";
+}
+
 /** How a received value is quoted back to the caller. Strings keep their quotes; nothing is elided. */
-function describe(value: unknown): string {
+function describe(value: CommandArgValue): string {
   if (value === undefined) {
     return "missing";
   }
-  return typeof value === "string" ? `"${value}"` : `${typeof value} ${JSON.stringify(value)}`;
+  return isString(value) ? `"${value}"` : `${typeWordOf(value)} ${JSON.stringify(value)}`;
+}
+
+/** Whether a value is a `JxPath`: an array whose every segment is a string key or a numeric index. */
+function isPathSegments(value: CommandArgValue): value is (string | number)[] {
+  return Array.isArray(value) && value.every((segment) => isString(segment) || isNumber(segment));
 }
 
 /** A required string argument. */
 export function stringArg(commandId: string, args: CommandArgValues, key: string): string {
   const value = args[key];
-  if (typeof value !== "string" || value === "") {
+  if (!isString(value) || value === "") {
     throw refuse(commandId, key, `expected a non-empty string, got ${describe(value)}`);
   }
   return value;
@@ -67,7 +96,7 @@ export function optionalStringArg(
 /** A required finite number argument. `NaN` and `Infinity` are refusals, not values. */
 export function numberArg(commandId: string, args: CommandArgValues, key: string): number {
   const value = args[key];
-  if (typeof value !== "number" || !Number.isFinite(value)) {
+  if (!isNumber(value) || !Number.isFinite(value)) {
     throw refuse(commandId, key, `expected a finite number, got ${describe(value)}`);
   }
   return value;
@@ -84,7 +113,7 @@ export function numberArg(commandId: string, args: CommandArgValues, key: string
  */
 export function integerArg(commandId: string, args: CommandArgValues, key: string): number {
   const value = args[key];
-  if (typeof value !== "number" || !Number.isInteger(value)) {
+  if (!isNumber(value) || !Number.isInteger(value)) {
     throw refuse(commandId, key, `expected an integer, got ${describe(value)}`);
   }
   return value;
@@ -116,7 +145,7 @@ export function boundedNumberArg(
 /** A required boolean argument. A setter's whole point is that `false` is a value, so no default. */
 export function booleanArg(commandId: string, args: CommandArgValues, key: string): boolean {
   const value = args[key];
-  if (typeof value !== "boolean") {
+  if (!isBoolean(value)) {
     throw refuse(commandId, key, `expected a boolean, got ${describe(value)}`);
   }
   return value;
@@ -136,7 +165,9 @@ export function enumArg<T extends string>(
   declared: readonly T[],
 ): T {
   const value = args[key];
-  if (typeof value !== "string" || !(declared as readonly string[]).includes(value)) {
+  // `find` hands back the DECLARED entry, typed `T`, which is the same string the caller sent.
+  const match = isString(value) ? declared.find((entry) => entry === value) : undefined;
+  if (match === undefined) {
     // `none` for an empty set: a derived enum (`derivedEnumProperty`) is honestly empty before the
     // Project supplies its values, and "declared: " with nothing after it reads as a truncation.
     throw refuse(
@@ -145,7 +176,7 @@ export function enumArg<T extends string>(
       `${describe(value)} is not declared — declared: ${declared.join(", ") || "none"}`,
     );
   }
-  return value as T;
+  return match;
 }
 
 /**
@@ -160,17 +191,14 @@ export function pathArg(
   key: string,
 ): (string | number)[] {
   const value = args[key];
-  if (
-    !Array.isArray(value) ||
-    !value.every((s) => typeof s === "string" || typeof s === "number")
-  ) {
+  if (!isPathSegments(value)) {
     throw refuse(
       commandId,
       key,
       `expected an array of path segments (strings or numbers), got ${describe(value)}`,
     );
   }
-  return value as (string | number)[];
+  return value;
 }
 
 /** A path argument that may be `null` — "select nothing" is a state a user can be in. */
@@ -203,17 +231,14 @@ export function pathListArg(
     throw refuse(commandId, key, `expected an array of document paths, got ${describe(value)}`);
   }
   return value.map((entry, i) => {
-    if (
-      !Array.isArray(entry) ||
-      !entry.every((s) => typeof s === "string" || typeof s === "number")
-    ) {
+    if (!isPathSegments(entry)) {
       throw refuse(
         commandId,
         key,
         `entry ${i} is not a document path — expected an array of segments, got ${describe(entry)}`,
       );
     }
-    return entry as (string | number)[];
+    return entry;
   });
 }
 
@@ -224,11 +249,39 @@ export function pathListArg(
 // Them ONE call site, so a schema that disagrees with its coercion is now a refusal rather than a
 // Defect a reviewer has to spot — which is what this module exists to prevent.
 
+/**
+ * The JSON Schema keywords a command property uses — what the builders below write and what
+ * {@link coerceArgs} reads. Read loosely: a keyword with no reader (`description`, `default`) is
+ * carried for the palette and the AI tool, and never consulted by the coercion.
+ */
+export interface PropertySchema {
+  description?: string;
+  title?: string;
+  default?: JsonValue;
+  type?: string | readonly string[];
+  /** Strings only: the `enum` row is {@link enumArg}, which admits nothing but a declared string. */
+  enum?: readonly string[];
+  const?: JsonValue;
+  oneOf?: readonly PropertySchema[];
+  items?: PropertySchema;
+  minimum?: number;
+  maximum?: number;
+}
+
+/** The object schema {@link argsSchema} writes, as {@link coerceArgs} reads it. */
+export interface CommandArgsSchema {
+  additionalProperties?: boolean;
+  properties?: Record<string, PropertySchema>;
+  required?: readonly string[];
+  /** Always `"object"` as {@link argsSchema} writes it; the coercion never reads it. */
+  type?: string;
+}
+
 /** `{ type: "object", properties, required, additionalProperties: false }` in one call. */
 export function argsSchema(
-  properties: Record<string, object>,
+  properties: Record<string, PropertySchema>,
   required: readonly string[] = Object.keys(properties),
-): object {
+): CommandArgsSchema {
   return {
     additionalProperties: false,
     properties,
@@ -238,7 +291,7 @@ export function argsSchema(
 }
 
 /** A string property constrained to a declared set, with the human sentence the palette shows. */
-export function enumProperty(declared: readonly string[], description: string): object {
+export function enumProperty(declared: readonly string[], description: string): PropertySchema {
   return { description, enum: [...declared], type: "string" };
 }
 
@@ -261,7 +314,7 @@ export function enumProperty(declared: readonly string[], description: string):
 export function derivedEnumProperty(
   declared: () => readonly string[],
   description: string,
-): object {
+): PropertySchema {
   return {
     description,
     get enum() {
@@ -275,17 +328,17 @@ export function derivedEnumProperty(
 export function numberProperty(
   description: string,
   bounds: { minimum?: number; maximum?: number } = {},
-): object {
+): PropertySchema {
   return { description, type: "number", ...bounds };
 }
 
 /** A boolean property. Named `open`/`enabled`/… by the caller; the description carries the sense. */
-export function booleanProperty(description: string): object {
+export function booleanProperty(description: string): PropertySchema {
   return { description, type: "boolean" };
 }
 
 /** A `JxPath` property — an array of string keys and numeric indexes. */
-export function pathProperty(description: string, nullable = false): object {
+export function pathProperty(description: string, nullable = false): PropertySchema {
   const path = {
     items: { type: ["string", "number"] },
     type: "array",
@@ -294,7 +347,7 @@ export function pathProperty(description: string, nullable = false): object {
 }
 
 /** A property holding a LIST of `JxPath`s — an array of arrays of segments. */
-export function pathListProperty(description: string): object {
+export function pathListProperty(description: string): PropertySchema {
   return {
     description,
     items: { items: { type: ["string", "number"] }, type: "array" },
@@ -303,7 +356,7 @@ export function pathListProperty(description: string): object {
 }
 
 /** A free-form string property. */
-export function stringProperty(description: string): object {
+export function stringProperty(description: string): PropertySchema {
   return { description, type: "string" };
 }
 
@@ -314,24 +367,6 @@ export function stringProperty(description: string): object {
 // Validator that agrees with them today. What the schema cannot say (a breakpoint the document
 // Defines, a path that addresses a node) stays in `run`; the schema owns the shape.
 
-/** The JSON Schema keywords a command property uses. Read loosely; unknown keywords are ignored. */
-interface PropertySchema {
-  type?: string | readonly string[];
-  enum?: readonly unknown[];
-  const?: unknown;
-  oneOf?: readonly PropertySchema[];
-  items?: PropertySchema;
-  minimum?: number;
-  maximum?: number;
-}
-
-/** The object schema `argsSchema` writes, as {@link coerceArgs} reads it. */
-interface ArgsSchemaShape {
-  properties?: Record<string, PropertySchema>;
-  required?: readonly string[];
-  additionalProperties?: boolean;
-}
-
 /**
  * The rows of {@link coerceArgs}'s dispatch table, by name.
  *
@@ -361,7 +396,7 @@ function isPathSegmentTypes(types: readonly string[]): boolean {
 
 /** A single JSON type name, or the list form `["number", "null"]`, as a list. */
 function typesOf(type: string | readonly string[]): readonly string[] {
-  return Array.isArray(type) ? type : [type as string];
+  return isString(type) ? [type] : type;
 }
 
 /**
@@ -371,8 +406,8 @@ function typesOf(type: string | readonly string[]): readonly string[] {
  * getter, and this function only classifies. The getter is read by the `enum` row when the value is
  * coerced, which is what makes the list live at that moment rather than at classification.
  */
-export function describeShape(property: object): CoercionRow {
-  const p = property as PropertySchema;
+export function coercionRowOf(property: PropertySchema): CoercionRow {
+  const p = property;
   if ("enum" in p) {
     return "enum";
   }
@@ -427,28 +462,28 @@ export function describeShape(property: object): CoercionRow {
 }
 
 /** Whether a value is of one JSON type. `number` means FINITE, as {@link numberArg} already insists. */
-function isJsonType(type: string, value: unknown): boolean {
+function isJsonType(type: string, value: CommandArgValue): boolean {
   switch (type) {
     case "null": {
       return value === null;
     }
     case "boolean": {
-      return typeof value === "boolean";
+      return isBoolean(value);
     }
     case "string": {
-      return typeof value === "string";
+      return isString(value);
     }
     case "number": {
-      return typeof value === "number" && Number.isFinite(value);
+      return isNumber(value) && Number.isFinite(value);
     }
     case "integer": {
-      return typeof value === "number" && Number.isInteger(value);
+      return isNumber(value) && Number.isInteger(value);
     }
     case "array": {
       return Array.isArray(value);
     }
     case "object": {
-      return typeof value === "object" && value !== null && !Array.isArray(value);
+      return isNonNullObject(value) && !Array.isArray(value);
     }
     default: {
       break;
@@ -478,17 +513,18 @@ export function typedArg(
   args: CommandArgValues,
   key: string,
   types: readonly string[],
-): unknown {
+): JsonValue {
   const value = args[key];
-  if (!types.some((type) => isJsonType(type, value))) {
+  // `undefined` is admitted by no JSON type, so the first test only states what the second proves.
+  if (value === undefined || !types.some((type) => isJsonType(type, value))) {
     throw refuse(commandId, key, `expected ${listTypes(types)}, got ${describe(value)}`);
   }
   return value;
 }
 
 /** One line per row, for the sentence a `oneOf` refusal prints when no branch admits the value. */
-function shapeOf(property: PropertySchema): string {
-  switch (describeShape(property)) {
+function expectedValueText(property: PropertySchema): string {
+  switch (coercionRowOf(property)) {
     case "enum": {
       return `one of ${(property.enum ?? []).map((v) => describe(v)).join(" | ")}`;
     }
@@ -496,7 +532,7 @@ function shapeOf(property: PropertySchema): string {
       return `the constant ${describe(property.const)}`;
     }
     case "one-of": {
-      return (property.oneOf ?? []).map((branch) => shapeOf(branch)).join(" or ");
+      return (property.oneOf ?? []).map((branch) => expectedValueText(branch)).join(" or ");
     }
     case "typed": {
       return listTypes(typesOf(property.type ?? []));
@@ -545,7 +581,7 @@ function oneOfArg(
   args: CommandArgValues,
   key: string,
   branches: readonly PropertySchema[],
-): unknown {
+): CommandArgValue {
   const value = args[key];
   const refusals: unknown[] = [];
   for (const branch of branches) {
@@ -567,7 +603,7 @@ function oneOfArg(
   throw refuse(
     commandId,
     key,
-    `expected ${branches.map((branch) => shapeOf(branch)).join(" or ")}, got ${describe(value)}`,
+    `expected ${branches.map((branch) => expectedValueText(branch)).join(" or ")}, got ${describe(value)}`,
   );
 }
 
@@ -577,11 +613,11 @@ function coerceProperty(
   args: CommandArgValues,
   key: string,
   property: PropertySchema,
-): unknown {
-  switch (describeShape(property)) {
+): CommandArgValue {
+  switch (coercionRowOf(property)) {
     case "enum": {
       // The read of `property.enum` is HERE — a derived list is resolved at coercion time.
-      return enumArg(commandId, args, key, (property.enum ?? []) as readonly string[]);
+      return enumArg(commandId, args, key, property.enum ?? []);
     }
     case "const": {
       const value = args[key];
@@ -652,12 +688,8 @@ function coerceProperty(
  * `run` body keeps its own `stringArg(...)` lines as typed readers and can never disagree with this
  * pass, because they are the same functions reading the same values.
  */
-export function coerceArgs(
-  commandId: string,
-  schema: object,
-  args: CommandArgValues,
-): CommandArgValues {
-  const spec = schema as ArgsSchemaShape;
+export function coerceArgs(commandId: string, schema: CommandArgsSchema, args: CommandArgValues) {
+  const spec = schema;
   const properties = spec.properties ?? {};
   const declared = Object.keys(properties);
   const required = spec.required ?? [];

package/src/commands/context.ts

@@ -23,6 +23,8 @@
 
 import type { KeyScope } from "./levels";
 import type { JxPath } from "../state";
+import { DEFAULT_WORKSPACE } from "../workspace/workspace-ids";
+import type { WorkspaceId } from "../workspace/workspace-ids";
 
 /** PAL-derived capability keys. One `when` clause replaces a scattered `if (platform.x)`. */
 export const CAPABILITIES = [
@@ -35,6 +37,11 @@ export const CAPABILITIES = [
   /* The image editor's gate. A backend that cannot hand Studio a project file's raw bytes cannot
      decode one, so the Image mode is not offered at all rather than offered and then failing. */
   "readFileBytes",
+  /* The Publish family's host question (studio.md §22.8): the host can reach the Cloudflare API
+     (`cfApi`), so it can connect a provider, deploy and read deployments. Whether it can open a
+     pull request is not a key: no record is refused on it. Send for review is a destination
+     inside the workspace, refused by the flow with its reason (`publish/publish-changes.ts`). */
+  "publish",
 ] as const;
 
 export type Capability = (typeof CAPABILITIES)[number];
@@ -55,10 +62,11 @@ export type EditorKind =
   | "grid"
   | "code"
   | "diff"
-  | "library"
   | "config"
+  | "tokens"
   | "entry"
   | "media"
+  | "home"
   | "none";
 
 /** The Canvas view axis — one control, three values (§4.2). */
@@ -81,36 +89,39 @@ export type CanvasView = "edit" | "design" | "preview";
  */
 
 /** The `canvasMode` strings, mapped onto the editor each one actually names. */
-const EDITOR_KIND_BY_MODE: Readonly<Record<string, EditorKind>> = {
-  design: "canvas",
-  edit: "canvas",
+const EDITOR_KIND_BY_MODE = new Map<string, EditorKind>([
+  ["design", "canvas"],
+  ["edit", "canvas"],
   /* The Entry editor — `content/entry-editor.ts`'s ENTRY_MODE. A form over ONE content entry's
      frontmatter, typed by its collection's schema; the same document the canvas edits the body of,
      which is why it is a mode of that tab rather than a tab of its own. */
-  entry: "entry",
-  "git-diff": "diff",
-  grid: "grid",
-  manage: "library",
+  ["entry", "entry"],
+  ["git-diff", "diff"],
+  ["grid", "grid"],
+  /* A workspace's home (`workspace/workspace-home.ts`): the surface a workspace opens on when none
+     of its own tabs is open. No document, no selection, nothing to paste into, so not the Canvas
+     key scope a mode this map did not know would fall into. */
+  ["content-home", "home"],
+  ["media-home", "home"],
+  ["publish-home", "home"],
   /* The Media viewer — `media/media-pane.ts`. An image, a video, a font specimen: files the studio
      can SHOW but has no document model for, which is why clicking one used to end in "No format
      class imported for …", advice that means nothing about a PNG. */
-  media: "media",
-  preview: "canvas",
-  /* Project Settings — `settings/settings-document.ts`'s SETTINGS_MODE. A form over `project.json`,
-     which is a configuration object and not a document tree; `stylebook` (Project Styles) is the
-     second editor over that same document and answers `config` for the same reason. */
-  settings: "config",
-  source: "code",
-  stylebook: "config",
-};
+  ["media", "media"],
+  ["preview", "canvas"],
+  ["source", "code"],
+  ["stylebook", "config"],
+  /* The Variables view (`style/variables-view.ts`): a form over `project.json`'s custom
+     properties, nothing to paste into, so the global key scope rather than the Canvas one. */
+  ["tokens", "tokens"],
+]);
 
 /**
  * The editor kind a mode string names.
  *
  * An unknown mode reads as Canvas, and that default is only for modes STUDIO DOES NOT OWN: a format
  * declares its own list (`format.studio.modes`) and every mode declared that way is a view of the
- * artboard. A mode Studio itself introduces is not covered by it and belongs in the map above —
- * which is what `settings` was not.
+ * artboard. A mode Studio itself introduces is not covered by it and belongs in the map above.
  */
 /**
  * Human names for the editor kinds, so no surface prints an enum at a reader — and so two surfaces
@@ -121,25 +132,28 @@ const EDITOR_KIND_BY_MODE: Readonly<Record<string, EditorKind>> = {
 export const EDITOR_KIND_LABELS: Readonly<Record<EditorKind, string>> = {
   canvas: "Canvas",
   code: "Code",
-  config: "Project Styles",
+  /* The Styles workspace's three views of `project.json` are named for what each one edits:
+     Elements (element defaults by tag, the `stylebook` editor), Variables and Code. */
+  config: "Elements",
   diff: "Diff",
   entry: "Entry",
   grid: "Grid",
+  home: "Home",
   media: "Media",
-  library: "Library",
   none: "None",
+  tokens: "Variables",
 };
 
 export function editorKindForMode(mode: string): EditorKind {
-  return EDITOR_KIND_BY_MODE[mode] ?? "canvas";
+  return EDITOR_KIND_BY_MODE.get(mode) ?? "canvas";
 }
 
 /** Only the three canvas modes carry a view. */
-const CANVAS_VIEW_BY_MODE: Readonly<Record<string, CanvasView>> = {
-  design: "design",
-  edit: "edit",
-  preview: "preview",
-};
+const CANVAS_VIEW_BY_MODE = new Map<string, CanvasView>([
+  ["design", "design"],
+  ["edit", "edit"],
+  ["preview", "preview"],
+]);
 
 /**
  * The Canvas view a mode names — the neutral "design" for a mode that has none.
@@ -147,7 +161,7 @@ const CANVAS_VIEW_BY_MODE: Readonly<Record<string, CanvasView>> = {
  * Meaningful only where {@link editorKindForMode} answers `"canvas"`; every reader pairs the two.
  */
 export function canvasViewForMode(mode: string): CanvasView {
-  return CANVAS_VIEW_BY_MODE[mode] ?? "design";
+  return CANVAS_VIEW_BY_MODE.get(mode) ?? "design";
 }
 
 /** Facts a command may be gated on. Every field is a plain value; predicates read, never write. */
@@ -164,6 +178,15 @@ export interface CommandContext {
     behind: number;
     dirtyCount: number;
   };
+  /**
+   * Which of the five workspaces is on screen (`shell.workspace`). A record or a panel whose
+   * surface belongs to one workspace gates on this, and every builder of a context — the live one,
+   * `panelContext()` and this module's empty one — has to fill it, or a predicate reads the default
+   * and silently never holds.
+   */
+  workspace: {
+    id: WorkspaceId;
+  };
   document: {
     open: boolean;
     dirty: boolean;
@@ -293,6 +316,7 @@ export function emptyContext(): CommandContext {
   return {
     project: { open: false, isSite: false, isRepo: false, isMultilingual: false },
     git: { ahead: 0, behind: 0, dirtyCount: 0 },
+    workspace: { id: DEFAULT_WORKSPACE },
     document: { open: false, dirty: false, mode: "", canUndo: false, canRedo: false },
     editor: { kind: "none" },
     canvas: { view: "design" },
@@ -319,6 +343,7 @@ export function emptyContext(): CommandContext {
       windowControls: false,
       findReferences: false,
       readFileBytes: false,
+      publish: false,
     },
   };
 }
@@ -332,6 +357,8 @@ export function emptyContext(): CommandContext {
  */
 export function makeContext(patch: CommandContextPatch = {}): CommandContext {
   const base = emptyContext();
+  /* SAFETY: a `CommandContextPatch` is a mapped type over `keyof CommandContext`, so every own key
+     it carries is a context group; `Object.keys` only widens those names to `string`. */
   for (const key of Object.keys(patch) as (keyof CommandContext)[]) {
     const group = patch[key];
     if (group) {