@unoverse-platform/studio 0.1.4 → 0.1.5

package/index.html

@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>unoverse studio</title>
   </head>
   <body>

package/local/authoring.ts

@@ -0,0 +1,101 @@
+/**
+ * COMPLETION VOCABULARY for the source pane.
+ *
+ * THERE IS ONE LINTER, and it is not here. The rules live in
+ * `@unoverse-platform/base/src/lint/rx/`, and the editor lints unsaved text by handing that
+ * library an overlay (`lintDefinitions(rxHome, { overlay })`), so the squiggles a developer
+ * sees are the same rules publish and CI apply. An approximation of those rules in the
+ * editor would be a second linter, which is exactly what the shared library exists to
+ * prevent. This file adds no rule and judges nothing.
+ *
+ * What it does serve is the closed vocabulary as DATA, for completion: the primitive set,
+ * the style keys, and the project's own token names. The sets are imported from the same
+ * library, so the list offered is the list allowed. Tokens come from the resolved theme,
+ * which is what the renderer actually resolves against, so a token offered is a token that
+ * renders. This is why completion is worth having here at all: with a closed vocabulary a
+ * completion list is not a hint, it is the whole legal set, and it knows the developer's
+ * real tokens in a way a JSON Schema in a text editor cannot.
+ *
+ * See docs/architecture/LOCAL_STUDIO.md §Authoring in Studio.
+ */
+import { resolve } from "path";
+import { existsSync, readdirSync } from "fs";
+
+/** The library's closed sets, imported rather than restated. */
+export interface Vocabulary {
+  primitives: string[];
+  styleKeys: string[];
+  conditionKeys: string[];
+  dimensionKeys: string[];
+  /** Token names by group, from the project's own resolved theme. */
+  tokens: { color: string[]; space: string[]; font: string[]; lineHeight: string[]; radius: string[]; shadow: string[] };
+  /** Atom names, for `Ref.ref`. */
+  atoms: string[];
+  /** Component names, for `ComponentSlot` and component refs. */
+  components: string[];
+}
+
+type LintLib = {
+  PRIMITIVES: Set<string>;
+  STYLE_KEYS: Set<string>;
+  CONDITION_KEYS: Set<string>;
+  DIMENSION_KEYS: Set<string>;
+  RAW_VALUE: RegExp;
+};
+
+/**
+ * The completion payload.
+ *
+ * Token groups come from the resolved theme, which is what the renderer actually resolves
+ * against, so a token offered here is a token that renders. A theme that fails to resolve
+ * yields empty groups rather than a guess.
+ */
+export function vocabulary(
+  vocab: LintLib,
+  theme: unknown,
+  atoms: { name?: string }[],
+  components: { name?: string }[],
+): Vocabulary {
+  const group = (key: string): string[] => {
+    const t = (theme as Record<string, Record<string, unknown>> | null)?.[key];
+    return t && typeof t === "object" ? Object.keys(t).sort() : [];
+  };
+  return {
+    primitives: [...vocab.PRIMITIVES].sort(),
+    styleKeys: [...vocab.STYLE_KEYS].sort(),
+    conditionKeys: [...vocab.CONDITION_KEYS].sort(),
+    dimensionKeys: [...vocab.DIMENSION_KEYS].sort(),
+    tokens: {
+      color: group("color"),
+      space: group("space"),
+      /**
+       * `font` RESOLVES AGAINST `theme.text`, not `theme.font`.
+       *
+       * The resolved theme has no `font` group: `fonts` holds families and `text` holds the
+       * semantic scale the style key actually uses (`style.ts`: `theme.text[s.font]`).
+       * Reading `font` returned an empty list, so `font:` was the one style key offering no
+       * completion at all, which is how an invalid token got typed in the first place.
+       */
+      font: group("text"),
+      lineHeight: group("lineHeight"),
+      radius: group("radius"),
+      shadow: group("shadow"),
+    },
+    atoms: atoms.map((a) => a.name ?? "").filter(Boolean).sort(),
+    components: components.map((c) => c.name ?? "").filter(Boolean).sort(),
+  };
+}
+
+/** Atom names off disk, for completion of `Ref.ref`. */
+export function atomNames(projectRoot: string): { name: string }[] {
+  const dirs = [resolve(projectRoot, "rx/marketplace/atoms"), resolve(projectRoot, "rx/atoms")];
+  const names = new Set<string>();
+  for (const d of dirs) {
+    if (!existsSync(d)) continue;
+    for (const e of readdirSync(d)) {
+      const m = /^(.*)\.(ya?ml|json)$/.exec(e);
+      if (m) names.add(m[1]);
+    }
+  }
+  return [...names].sort().map((name) => ({ name }));
+}

package/local/catalog.ts

@@ -25,6 +25,10 @@ type Loaders = {
   listThemeNames: (org: string) => string[];
   resolveTheme: (name: string) => unknown;
   DEFAULT_ORG: string;
+  /** A project's on-disk home. The writable set is built from these (see source.ts). */
+  projectDir: (name: string) => string;
+  /** A component id's on-disk folder, either tier. Null for a flat, folderless one. */
+  componentFolder: (ref: string) => string | null;
 };
 
 /**
@@ -101,5 +105,7 @@ export async function loadCatalog(
     listThemeNames: theme.listThemeNames as Loaders["listThemeNames"],
     resolveTheme: theme.resolveTheme as Loaders["resolveTheme"],
     DEFAULT_ORG: theme.DEFAULT_ORG as string,
+    projectDir: defs.projectDir as Loaders["projectDir"],
+    componentFolder: defs.componentFolder as Loaders["componentFolder"],
   };
 }

package/local/mcp.ts

@@ -0,0 +1,260 @@
+/**
+ * THE STUDIO MCP: a developer's Claude, authoring against their own folder.
+ *
+ * Same flow as Canvas. The developer clicks "Connect agent", Studio mints a short
+ * single-use code, they paste it into Claude, and `bindProject` redeems it. Until a session
+ * is bound, every other tool refuses.
+ *
+ * NO REDIS, and none needed: Canvas stores codes there because a universe is several
+ * processes serving many users. Studio is one process serving one developer, so the code
+ * lives in memory and dies with the server, which is the correct lifetime for it.
+ *
+ * THIS SERVER OWNS NO RULES. Saving goes through the same lint-gated chokepoint the editor
+ * uses (source.ts), linting is the shared library, and completion data is the same
+ * vocabulary. That is why it stays small: the guardrails already exist below it, and an
+ * agent gets exactly the ones the human gets.
+ *
+ * See docs/architecture/LOCAL_STUDIO.md §The connected agent.
+ */
+import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+/** Human-typeable, unambiguous alphabet. The same one Canvas uses (no 0/O/1/I/L). */
+const CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+const CODE_TTL_MS = 10 * 60 * 1000;
+
+let pending: { code: string; expires: number } | null = null;
+
+export function mintPairingCode(): { code: string; expiresInSeconds: number } {
+  const b = randomBytes(8);
+  let s = "";
+  for (let i = 0; i < 8; i++) s += CODE_ALPHABET[b[i] % CODE_ALPHABET.length];
+  const code = `${s.slice(0, 4)}-${s.slice(4)}`;
+  pending = { code, expires: Date.now() + CODE_TTL_MS };
+  return { code, expiresInSeconds: CODE_TTL_MS / 1000 };
+}
+
+/** Redeem and burn. A lingering copy in a transcript is inert. */
+function redeem(raw: string): boolean {
+  const code = raw.trim().toUpperCase();
+  if (!pending || pending.code !== code || Date.now() > pending.expires) return false;
+  pending = null;
+  return true;
+}
+
+export interface McpDeps {
+  projectRoot: string;
+  /** The catalog loaders, so the agent reads definitions the same way the screens do. */
+  catalog: () => Promise<{
+    listDefinitions: (kind: string, org?: string) => unknown[];
+    loadDefinition: (ref: string, kind: string) => unknown;
+    listOrgs: () => string[];
+  }>;
+  /** Files behind a definition, and their writability. */
+  sourceFiles: (uri: string) => { path: string; rel: string; writable: boolean }[];
+  readSource: (path: string) => { text: string; writable: boolean } | null;
+  /** The lint-gated write chokepoint. Identical to the one the editor presses. */
+  saveSource: (path: string, text: string) => Promise<{ saved: boolean; error?: string; findings?: unknown[] }>;
+  lintProject: () => Promise<{ problems: unknown[] }>;
+  /** What the developer last picked in the preview. */
+  selection: () => Record<string, unknown> | null;
+  vocabulary: () => Promise<unknown>;
+}
+
+const SKILL_DIRS = ["vendor/skills/unoverse-create", "../../prompts/skills/unoverse-create"];
+
+/** The vendored authoring skill, which is how an agent learns the rules before writing. */
+function authoringSkill(appRoot: string): string {
+  for (const d of SKILL_DIRS) {
+    const p = resolve(appRoot, d, "SKILL.md");
+    if (existsSync(p)) return readFileSync(p, "utf8");
+  }
+  return "No authoring skill is vendored with this Studio build.";
+}
+
+type Tool = {
+  description: string;
+  inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[] };
+  run: (args: Record<string, any>) => Promise<unknown>;
+};
+
+/**
+ * The tool surface, deliberately short.
+ *
+ * Everything an agent needs to author and nothing that duplicates a rule: read the project,
+ * learn the rules, read a definition and its files, save through the gate, lint, and ask
+ * what the developer is pointing at.
+ */
+export function buildTools(deps: McpDeps, appRoot: string): Record<string, Tool> {
+  let bound = false;
+  const needsBinding = () => {
+    if (!bound) throw new Error("Not bound. Call bindProject with the code from Studio's 'Connect agent' button.");
+  };
+
+  return {
+    bindProject: {
+      description:
+        "Bind this session to the developer's Studio project using the pairing code shown by Studio's 'Connect agent' button. Call this first; nothing else works until you do.",
+      inputSchema: { type: "object", properties: { code: { type: "string" } }, required: ["code"] },
+      run: async ({ code }) => {
+        if (!redeem(String(code ?? ""))) throw new Error("Invalid or expired pairing code. Generate a fresh one in Studio.");
+        bound = true;
+        const c = await deps.catalog();
+        return {
+          bound: true,
+          projectRoot: deps.projectRoot,
+          projects: c.listOrgs(),
+          note: "Saves are lint-gated and installed assets are read-only. Read the authoring skill before writing.",
+        };
+      },
+    },
+
+    readAuthoringSkill: {
+      description: "The rules for authoring unoverse definitions. Read this before writing or editing any definition.",
+      inputSchema: { type: "object", properties: {} },
+      run: async () => {
+        needsBinding();
+        return { skill: authoringSkill(appRoot) };
+      },
+    },
+
+    getVocabulary: {
+      description:
+        "The closed vocabulary: the primitive set, the style keys, and THIS project's own token names from its resolved theme. A value outside these will fail lint.",
+      inputSchema: { type: "object", properties: {} },
+      run: async () => {
+        needsBinding();
+        return deps.vocabulary();
+      },
+    },
+
+    listDefinitions: {
+      description: "The project's components or templates.",
+      inputSchema: {
+        type: "object",
+        properties: { kind: { type: "string", enum: ["component", "template", "atom"] } },
+        required: ["kind"],
+      },
+      run: async ({ kind }) => {
+        needsBinding();
+        const c = await deps.catalog();
+        return { definitions: c.listDefinitions(String(kind)) };
+      },
+    },
+
+    readDefinition: {
+      description:
+        "One definition, composed, plus the source files behind it and whether each may be written. Installed assets read but never write.",
+      inputSchema: { type: "object", properties: { uri: { type: "string" } }, required: ["uri"] },
+      run: async ({ uri }) => {
+        needsBinding();
+        const c = await deps.catalog();
+        const ref = String(uri).replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "");
+        const kind = /\/(apps|templates)\//.test(String(uri)) ? "template" : /\/atoms\//.test(String(uri)) ? "atom" : "component";
+        return { definition: c.loadDefinition(ref, kind), files: deps.sourceFiles(String(uri)) };
+      },
+    },
+
+    readSource: {
+      description: "One source file's text.",
+      inputSchema: { type: "object", properties: { path: { type: "string" } }, required: ["path"] },
+      run: async ({ path }) => {
+        needsBinding();
+        const found = deps.readSource(String(path));
+        if (!found) throw new Error(`Not readable: ${path}`);
+        return found;
+      },
+    },
+
+    saveDefinition: {
+      description:
+        "Write a source file. The linter runs and a failing write is ROLLED BACK, so a refusal means nothing changed on disk. Installed assets are refused outright.",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" }, text: { type: "string" } },
+        required: ["path", "text"],
+      },
+      run: async ({ path, text }) => {
+        needsBinding();
+        return deps.saveSource(String(path), String(text));
+      },
+    },
+
+    lintProject: {
+      description: "Lint every definition. The same rules that gate a save, a publish and CI.",
+      inputSchema: { type: "object", properties: {} },
+      run: async () => {
+        needsBinding();
+        return deps.lintProject();
+      },
+    },
+
+    getSelection: {
+      description:
+        "What the developer is pointing at: the element they picked in Studio's preview, as a file, an offset and the node's path. Call this when an instruction says 'this' or 'that'.",
+      inputSchema: { type: "object", properties: {} },
+      run: async () => {
+        needsBinding();
+        return deps.selection() ?? { empty: true, note: "Nothing picked. Ask the developer to use Studio's pick tool." };
+      },
+    },
+  };
+}
+
+/**
+ * JSON-RPC over a single POST, which is all a local MCP client needs.
+ *
+ * The SDK's transport exists for sessions, SSE and resumability; none of that applies to a
+ * loopback tool talking to one editor, so this handles `initialize`, `tools/list` and
+ * `tools/call` directly rather than carrying that machinery.
+ */
+export async function handleMcp(
+  req: IncomingMessage,
+  res: ServerResponse,
+  body: unknown,
+  tools: Record<string, Tool>,
+): Promise<void> {
+  const send = (payload: unknown, status = 200) => {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(payload));
+  };
+  const msg = body as { id?: unknown; method?: string; params?: any };
+  const reply = (result: unknown) => send({ jsonrpc: "2.0", id: msg?.id ?? null, result });
+  const fail = (code: number, message: string) => send({ jsonrpc: "2.0", id: msg?.id ?? null, error: { code, message } });
+
+  switch (msg?.method) {
+    case "initialize":
+      return reply({
+        protocolVersion: "2024-11-05",
+        capabilities: { tools: {} },
+        serverInfo: { name: "unoverse-studio", version: "1" },
+      });
+    case "notifications/initialized":
+      res.statusCode = 202;
+      return void res.end();
+    case "tools/list":
+      return reply({
+        tools: Object.entries(tools).map(([name, t]) => ({
+          name,
+          description: t.description,
+          inputSchema: t.inputSchema,
+        })),
+      });
+    case "tools/call": {
+      const tool = tools[msg.params?.name];
+      if (!tool) return fail(-32601, `Unknown tool: ${msg.params?.name}`);
+      try {
+        const out = await tool.run(msg.params?.arguments ?? {});
+        return reply({ content: [{ type: "text", text: JSON.stringify(out, null, 2) }] });
+      } catch (e) {
+        // A refusal is a RESULT, not a protocol error: the agent should read why and adjust.
+        return reply({ content: [{ type: "text", text: `Error: ${(e as Error).message}` }], isError: true });
+      }
+    }
+    default:
+      return fail(-32601, `Unsupported method: ${msg?.method}`);
+  }
+}