@xemahq/ui-kernel 0.11.0 → 0.11.2

package/src/vista/vista-tabs-manifest.ts

@@ -1,138 +0,0 @@
-/**
- * `.tabs.json` — the agent-authored tab manifest for a file-backed Vista panel.
- *
- * Lifted VERBATIM (guards included) out of the 4970-line Design-System-Builder
- * page, generalised over the artifact prefix, and re-keyed onto the kernel
- * {@link SurfaceKind} (Canopy §8.5). It is the ONE parser for this format; the
- * page no longer carries its own.
- *
- * ── The guards (all preserved, all fail-closed) ─────────────────────────────
- *   1. `version` MUST be exactly `1`.
- *   2. `tabs` MUST be an array.
- *   3. Every entry's `path` MUST be a string INSIDE the caller's artifact
- *      prefix — an agent cannot point a tab at an arbitrary workspace file.
- *   4. No `..` anywhere in a path — no traversal out of the prefix.
- *   5. A declared `kind` MUST be a member of {@link DECLARABLE_SURFACE_KINDS}.
- *      {@link SurfaceKind.Files} is UI-owned (the pinned browser tab) and can
- *      NEVER be declared by an agent.
- *   6. ANY violation rejects the WHOLE manifest (returns `null`) — the caller
- *      falls back to auto-discovery. A malformed file behaves exactly as an
- *      absent one; there is no partial acceptance and no silent coercion.
- *
- * Kind vocabulary note: the legacy `plain` literal is GONE. Plain text is
- * {@link SurfaceKind.Code} (a mono pane) — one kind, one renderer, no alias.
- */
-import { SurfaceKind } from '@xemahq/kernel-contracts/surface';
-
-import { surfaceKindForPath } from './vista-model';
-
-/**
- * The kinds an agent may declare in `.tabs.json`. Every one is file-backed.
- * `files` is deliberately absent (UI-owned); so are the host-coupled kinds
- * (`web`, `biome-route`, `object`, `graph`, `app`, `form`), which are not
- * addressable by a workspace path and are opened through `vista_open` instead.
- */
-export const DECLARABLE_SURFACE_KINDS: readonly SurfaceKind[] = [
-  SurfaceKind.Html,
-  SurfaceKind.Markdown,
-  SurfaceKind.Code,
-  SurfaceKind.Json,
-  SurfaceKind.Diff,
-  SurfaceKind.Pdf,
-  SurfaceKind.Image,
-  SurfaceKind.Media,
-];
-
-/** One declared tab. */
-export interface VistaTabSpec {
-  readonly path: string;
-  readonly kind: SurfaceKind;
-  readonly label?: string;
-}
-
-/** The parsed manifest. */
-export interface VistaTabsManifest {
-  readonly version: 1;
-  readonly tabs: readonly VistaTabSpec[];
-  /** Path of the tab the agent wants selected on open. */
-  readonly selectedPath?: string;
-}
-
-/** Options for {@link parseVistaTabsManifest}. */
-export interface VistaTabsManifestOptions {
-  /**
-   * Prefix every declared path MUST start with (e.g. `'deliverables/'`). The
-   * containment guard — an agent can only curate tabs over its own artifacts.
-   */
-  readonly pathPrefix: string;
-}
-
-function parseEntry(entry: unknown, pathPrefix: string): VistaTabSpec | null {
-  if (!entry || typeof entry !== 'object') {
-    return null;
-  }
-  const record = entry as Record<string, unknown>;
-  if (typeof record.path !== 'string') {
-    return null;
-  }
-  // Containment: inside the artifact prefix, and no traversal out of it.
-  if (!record.path.startsWith(pathPrefix)) {
-    return null;
-  }
-  if (record.path.includes('..')) {
-    return null;
-  }
-  const kind =
-    typeof record.kind === 'string'
-      ? (record.kind as SurfaceKind)
-      : surfaceKindForPath(record.path);
-  // `files` is UI-owned (the pinned file browser) and must never be declared by
-  // the agent — an out-of-set kind rejects the whole manifest.
-  if (!DECLARABLE_SURFACE_KINDS.includes(kind)) {
-    return null;
-  }
-  const label = typeof record.label === 'string' ? record.label : undefined;
-  return label === undefined
-    ? { path: record.path, kind }
-    : { path: record.path, kind, label };
-}
-
-/**
- * Parse a `.tabs.json` body. Returns `null` on ANY shape violation — the caller
- * falls back to auto-discovery. No silent coercion: a malformed file is as if
- * it were absent (the user sees the default view instead of a broken state).
- */
-export function parseVistaTabsManifest(
-  raw: string,
-  { pathPrefix }: VistaTabsManifestOptions,
-): VistaTabsManifest | null {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw) as unknown;
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== 'object') {
-    return null;
-  }
-  const record = parsed as Record<string, unknown>;
-  if (record.version !== 1) {
-    return null;
-  }
-  if (!Array.isArray(record.tabs)) {
-    return null;
-  }
-  const tabs: VistaTabSpec[] = [];
-  for (const entry of record.tabs) {
-    const tab = parseEntry(entry, pathPrefix);
-    if (tab === null) {
-      return null;
-    }
-    tabs.push(tab);
-  }
-  const selectedPath =
-    typeof record.selectedPath === 'string' ? record.selectedPath : undefined;
-  return selectedPath === undefined
-    ? { version: 1, tabs }
-    : { version: 1, tabs, selectedPath };
-}

package/src/vista/vista-tools.ts

@@ -1,232 +0,0 @@
-/**
- * The agent-facing Vista tool contract — `vista_open` / `vista_update` /
- * `vista_close` / `vista_list` (Canopy §8.2).
- *
- * This module is the BROWSER-side definition of those four calls: their names,
- * their argument shapes, their result shapes, and the dispatcher that performs
- * them against a {@link VistaTabsController}.
- *
- * ── One wire contract, two projections ──────────────────────────────────────
- * The server half lives in `canopy-api`'s `vista/vista-tool.contract.ts`. The
- * two files are VALUE-IDENTICAL by construction — same tool names, same
- * argument shapes, same {@link VistaToolError} members, same result envelope —
- * and both derive the `vista_open` argument from the kernel's
- * `VistaSurfaceSchema`, which is the single structural source of truth. They
- * are two projections rather than one import because this package is a React
- * UI package (a NestJS service must not depend on it) and the kernel contracts
- * package does not yet carry the three tiny argument schemas. Consolidating
- * them into `@xemahq/kernel-contracts/surface` is the correct end state; until
- * then, a change to either file MUST be mirrored in the other in the same
- * change-set, exactly like the curated `ConnectorKind` parity rule.
- *
- * ── How a call gets here ────────────────────────────────────────────────────
- * Vista is a BROWSER surface: no server can render a tab. So the backend never
- * "performs" these tools — it VALIDATES, applies its own tab projection,
- * RELAYS the call to the browser over the EXISTING agent-session realtime
- * channel, and returns the browser's {@link VistaToolResult} to the model
- * verbatim. A session where no panel answers returns
- * `{ ok: false, error: 'no-panel' }` — an explicit refusal, never a silent
- * success.
- *
- * The host binds `dispatchVistaTool` to its panel's controller and feeds it the
- * relayed `{ tool, args }`; see the host's `use-vista-tool-bridge`.
- */
-import { VistaSurfaceSchema } from '@xemahq/kernel-contracts/surface';
-import { z } from 'zod';
-
-import type { VistaSurfacePatch, VistaTabsController } from './use-vista-tabs';
-
-/** The closed set of Vista tools. Values are the wire tool names. */
-export enum VistaToolName {
-  Open = 'vista_open',
-  Update = 'vista_update',
-  Close = 'vista_close',
-  List = 'vista_list',
-}
-
-/**
- * `vista_open(surface) -> { tabId }`.
- *
- * The argument IS the kernel tab envelope — not a wrapper around it — so the
- * JSON Schema the model is shown is exactly `VistaSurface`. `kind` is an open
- * string on purpose: an unrecognised kind is NOT an error, it opens a tab that
- * renders the fallback card.
- */
-export const VistaOpenArgsSchema = VistaSurfaceSchema;
-export type VistaOpenArgs = z.infer<typeof VistaOpenArgsSchema>;
-
-/**
- * `vista_update(tabId, …) -> { updated: true }`.
- *
- * Flat, and deliberately narrower than {@link VistaSurfacePatch}: `kind` and
- * `version` are NOT patchable, because the browser has already resolved a
- * renderer for the live tab and swapping the kind under it would strand that
- * renderer. Close and re-open instead. Every remaining field is optional; an
- * empty patch is a no-op, not an error.
- */
-export const VistaUpdateArgsSchema = z.object({
-  tabId: z.string().min(1),
-  title: z.string().min(1).optional(),
-  payload: z.unknown().optional(),
-  pinned: z.boolean().optional(),
-});
-export type VistaUpdateArgs = z.infer<typeof VistaUpdateArgsSchema>;
-
-/** `vista_close(tabId) -> { closed: true }`. A pinned tab refuses to close. */
-export const VistaCloseArgsSchema = z.object({ tabId: z.string().min(1) });
-export type VistaCloseArgs = z.infer<typeof VistaCloseArgsSchema>;
-
-/** `vista_list() -> { tabs }`. No arguments. */
-export const VistaListArgsSchema = z.object({});
-export type VistaListArgs = z.infer<typeof VistaListArgsSchema>;
-
-/** Why a Vista tool call could not be performed. Closed set. */
-export enum VistaToolError {
-  /** No Vista panel answered the relay — nothing is on screen to drive. */
-  NoPanel = 'no-panel',
-  /** The arguments failed schema validation at a wire boundary. */
-  InvalidArgs = 'invalid-args',
-  /** The tool name is not a member of {@link VistaToolName}. */
-  UnknownTool = 'unknown-tool',
-  /** `tabId` names a tab that is not open. */
-  UnknownTab = 'unknown-tab',
-  /**
-   * The tab exists but refuses the operation — it is pinned (close), or it is
-   * a HOST tab whose content the host's own data flow owns (update). `detail`
-   * names which.
-   */
-  TabRefused = 'tab-refused',
-}
-
-/** The result envelope every Vista tool returns. */
-export type VistaToolResult<TValue = unknown> =
-  | { readonly ok: true; readonly value: TValue }
-  | {
-      readonly ok: false;
-      readonly error: VistaToolError;
-      readonly detail?: string;
-    };
-
-/**
- * Wire validator for {@link VistaToolResult}. The browser's answer crosses back
- * into the server and then into the model's context, so the server validates
- * the ENVELOPE with this shape before relaying it on — a browser cannot inject
- * an arbitrary object where a typed result is expected.
- */
-export const VistaToolResultSchema: z.ZodType<VistaToolResult> = z.union([
-  z.object({ ok: z.literal(true), value: z.unknown() }),
-  z.object({
-    ok: z.literal(false),
-    error: z.nativeEnum(VistaToolError),
-    detail: z.string().optional(),
-  }),
-]);
-
-/**
- * Perform a relayed Vista tool call against a mounted panel's controller.
- *
- * Fail-fast on bad input: arguments are re-validated here (the frontend never
- * trusts that the backend validated), and a violation returns
- * {@link VistaToolError.InvalidArgs} naming the offending path rather than a
- * partially-applied change. Pass `controller: null` for a document with no
- * mounted panel — that returns {@link VistaToolError.NoPanel}.
- */
-export function dispatchVistaTool(
-  controller: VistaTabsController | null,
-  tool: string,
-  args: unknown,
-): VistaToolResult {
-  if (controller === null) {
-    return { ok: false, error: VistaToolError.NoPanel };
-  }
-  switch (tool) {
-    case VistaToolName.Open: {
-      const parsed = VistaOpenArgsSchema.safeParse(args);
-      if (!parsed.success) {
-        return invalid(parsed.error);
-      }
-      return { ok: true, value: { tabId: controller.open(parsed.data) } };
-    }
-    case VistaToolName.Update: {
-      const parsed = VistaUpdateArgsSchema.safeParse(args);
-      if (!parsed.success) {
-        return invalid(parsed.error);
-      }
-      const { tabId, ...patch } = parsed.data;
-      const refusal = refusalFor(controller, tabId);
-      if (refusal !== null) {
-        return refusal;
-      }
-      if (!controller.update(tabId, patch)) {
-        // The tab is listed but not opened-tab-owned: it is a HOST tab, and a
-        // patch to it would be overwritten by the host's next reconcile.
-        return {
-          ok: false,
-          error: VistaToolError.TabRefused,
-          detail: `Tab "${tabId}" is host-owned; its content is driven by the host, not by vista_update.`,
-        };
-      }
-      return { ok: true, value: { updated: true } };
-    }
-    case VistaToolName.Close: {
-      const parsed = VistaCloseArgsSchema.safeParse(args);
-      if (!parsed.success) {
-        return invalid(parsed.error);
-      }
-      const { tabId } = parsed.data;
-      const refusal = refusalFor(controller, tabId);
-      if (refusal !== null) {
-        return refusal;
-      }
-      if (!controller.close(tabId)) {
-        return {
-          ok: false,
-          error: VistaToolError.TabRefused,
-          detail: `Tab "${tabId}" is pinned and cannot be closed.`,
-        };
-      }
-      return { ok: true, value: { closed: true } };
-    }
-    case VistaToolName.List: {
-      const parsed = VistaListArgsSchema.safeParse(args ?? {});
-      if (!parsed.success) {
-        return invalid(parsed.error);
-      }
-      return { ok: true, value: { tabs: controller.list() } };
-    }
-    default:
-      return {
-        ok: false,
-        error: VistaToolError.UnknownTool,
-        detail: `'${tool}' is not a Vista tool.`,
-      };
-  }
-}
-
-/**
- * `unknown-tab` when the panel does not hold `tabId` at all. Returning `null`
- * means the tab exists and the operation may proceed.
- */
-function refusalFor(
-  controller: VistaTabsController,
-  tabId: string,
-): VistaToolResult | null {
-  if (controller.list().some((tab) => tab.tabId === tabId)) {
-    return null;
-  }
-  return {
-    ok: false,
-    error: VistaToolError.UnknownTab,
-    detail: `No tab "${tabId}" is open.`,
-  };
-}
-
-function invalid(error: z.ZodError): VistaToolResult {
-  return {
-    ok: false,
-    error: VistaToolError.InvalidArgs,
-    detail: error.issues
-      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
-      .join('; '),
-  };
-}