@unoverse-platform/studio 0.1.0

package/local/plugin.ts

@@ -0,0 +1,401 @@
+/**
+ * The local Studio's file-reading host, as a Vite plugin.
+ *
+ * The Studio screens (../screens) fetch a small set of catalog routes. In Canvas those
+ * are served by a running universe. Here they are served straight off the developer's
+ * disk by the SAME loaders the server uses (see catalog.ts), so the screens are
+ * unchanged and there is no backend: no Postgres, no Redis, no engine, no Docker.
+ *
+ * Routes mirror the server's shapes exactly, because the screens parse those shapes:
+ *   GET /dev/orgs        GET /dev/themes?org=      GET /dev/components?org=
+ *   GET /dev/templates?org=   GET /dev/atoms
+ *   GET /local/theme?ref=     GET /local/definition?uri=
+ *   GET /skills  /skills/:name   GET /prompt-blocks
+ *   GET|POST /registry/state  (no database locally, see below)
+ *
+ * See docs/architecture/LOCAL_STUDIO.md.
+ */
+import { createRequire } from "node:module";
+import { resolve } from "path";
+import { readdirSync, existsSync, readFileSync, statSync } from "fs";
+import type { Plugin, ViteDevServer } from "vite";
+import { findProjectRoot, loadCatalog } from "./catalog.js";
+import { loadLocalNodes, type LocalNodes } from "./nodes.js";
+import { credentialsFromEnv, keyPresence, readEnv } from "./keys.js";
+
+/** JSON response helper matching the server's content type. */
+function json(res: import("http").ServerResponse, body: unknown, status = 200): void {
+  const text = JSON.stringify(body);
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(text);
+}
+
+/**
+ * Read a folder of markdown-with-frontmatter (skills, prompt blocks) into the shape
+ * the screens expect. Deliberately minimal: local Studio reads the developer's OWN
+ * files, and the frontmatter fields the screens display are name/description/category.
+ */
+interface MarkdownEntry {
+  /** Stable key the screens select on. Derived from the filename, like the server's. */
+  id: string;
+  name: string;
+  description: string;
+  category?: string;
+  version?: string;
+  filePath: string;
+  tags: string[];
+  /** Prompt blocks read `content`; skills read `instructions`. Same text, both named. */
+  content: string;
+  instructions: string;
+  whenToUse?: string;
+  triggers?: string[];
+  contentHash: string;
+}
+
+function readMarkdownLibrary(dir: string): MarkdownEntry[] {
+  if (!existsSync(dir)) return [];
+  const out: MarkdownEntry[] = [];
+  const walk = (d: string) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = resolve(d, e.name);
+      if (e.isDirectory()) {
+        walk(p);
+        continue;
+      }
+      if (!e.name.endsWith(".md")) continue;
+      const raw = readFileSync(p, "utf8");
+      const m = /^---\n([\s\S]*?)\n---\n?/.exec(raw);
+      const meta: Record<string, string> = {};
+      if (m) {
+        for (const line of m[1].split("\n")) {
+          const i = line.indexOf(":");
+          if (i > 0) meta[line.slice(0, i).trim()] = line.slice(i + 1).trim().replace(/^["']|["']$/g, "");
+        }
+      }
+      const body = m ? raw.slice(m[0].length) : raw;
+      // Skills are a FOLDER holding SKILL.md, so the folder names them. Prompt blocks
+      // are single files, so the filename does. Either way the id must be unique.
+      const base = e.name.replace(/\.md$/, "");
+      const id = base.toUpperCase() === "SKILL" ? d.split("/").pop()! : base;
+      const list = (v?: string) =>
+        v ? v.replace(/^\[|\]$/g, "").split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean) : [];
+      out.push({
+        id,
+        name: meta.name || id,
+        description: meta.description ?? "",
+        category: meta.category,
+        version: meta.version,
+        filePath: p,
+        tags: list(meta.tags),
+        content: body,
+        instructions: body,
+        whenToUse: meta.whenToUse,
+        triggers: list(meta.triggers),
+        // The server hashes content to detect drift. Offline nothing consumes it, but
+        // the screens type it as required, so give them something honest and stable.
+        contentHash: String(statSync(p).mtimeMs),
+      });
+    }
+  };
+  walk(dir);
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function localStudioHost(): Plugin {
+  let projectRoot: string;
+  let baseSrc: string;
+
+  return {
+    name: "local-studio-host",
+
+    configureServer(server: ViteDevServer) {
+      projectRoot = findProjectRoot();
+      /**
+       * The loaders live in `@unoverse-platform/base`. Studio reuses them rather than
+       * growing a second implementation that would drift.
+       *
+       * RESOLVED THROUGH NODE, not by walking the tree. This used to be
+       * `resolve(root, "../unoverse/server/src")`, which was two problems in one: it
+       * reached into another app's source, so Studio could never be published, and it
+       * silently broke the moment those files moved into `base` — the paths pointed at
+       * nothing and no test covered the path.
+       *
+       * Asking Node where the package is means it works from a checkout OR from
+       * node_modules, which is what makes standalone Studio possible.
+       */
+      baseSrc = resolve(
+        createRequire(import.meta.url).resolve("@unoverse-platform/base/package.json"),
+        "../src",
+      );
+
+      const ssr = (id: string) => server.ssrLoadModule(id) as Promise<Record<string, unknown>>;
+      const catalog = loadCatalog(baseSrc, ssr, projectRoot);
+      // Node packages load lazily: only when the Nodes section is first opened, so a
+      // developer authoring only design assets never pays for it at startup.
+      let nodesOnce: Promise<LocalNodes | null> | null = null;
+      const nodes = () => (nodesOnce ??= loadLocalNodes(baseSrc, ssr, projectRoot));
+
+      server.config.logger.info(`\n  Studio reading: ${resolve(projectRoot, "rx")}\n`);
+
+      server.middlewares.use(async (req, res, next) => {
+        const url = new URL(req.url ?? "/", "http://local");
+        const path = url.pathname;
+        // ADD A ROUTE HERE TOO. A case in the switch below that is not in this list never
+        // runs: the request falls through to Vite, which answers with the app's HTML and a
+        // 200. That has now cost three separate bugs (the /api allowlist, the dev proxy for
+        // /.well-known and /publish), each of which looked like a missing route rather than
+        // a filtered one.
+        if (!/^\/(dev|local|skills|prompt-blocks|registry|nodes|keys|execute|publish)\b/.test(path)) return next();
+
+        /** Read a JSON request body. */
+        const body = async (): Promise<Record<string, unknown>> => {
+          const chunks: Buffer[] = [];
+          for await (const c of req) chunks.push(c as Buffer);
+          const raw = Buffer.concat(chunks).toString("utf8");
+          return raw ? (JSON.parse(raw) as Record<string, unknown>) : {};
+        };
+
+        try {
+          const c = await catalog;
+          const org = url.searchParams.get("org") ?? undefined;
+
+          switch (true) {
+            // Where Studio is reading and writing, in absolute terms. Shown in the UI:
+            // a developer must be able to SEE which folder their keys and nodes come
+            // from, not be told to trust a relative path.
+            case path === "/local/info":
+              return json(res, {
+                projectRoot,
+                rx: resolve(projectRoot, "rx"),
+                nodes: resolve(projectRoot, "nodes"),
+                envFiles: [resolve(projectRoot, "..", ".env"), resolve(projectRoot, ".env")],
+              });
+
+            /**
+             * PUBLISH, in two calls: plan then send.
+             *
+             * It runs HERE rather than in the browser because publishing reads the
+             * developer's disk: their definitions, and the design system they built on.
+             * A browser cannot, and a server that could would be a server this tool
+             * deliberately does not have.
+             *
+             * The token is passed per request and never stored. Studio holds it in the
+             * OIDC session for the tab (UniverseSession) and hands it over for the one
+             * call; local Studio writes no secret to disk (local/keys.ts), and connecting
+             * to a universe must not be the thing that breaks that.
+             *
+             * Same functions the CLI uses (`unoverse publish assets`), so the two cannot
+             * disagree about what a publish is.
+             */
+            case path === "/publish/plan" || path === "/publish/send": {
+              const b = await body();
+              const project = String(b.project ?? "");
+              const universe = String(b.universe ?? "");
+              const token = String(b.token ?? "");
+              if (!project || !universe || !token)
+                return json(res, { error: "project, universe and token are required" }, 400);
+
+              // Loaded through Vite's SSR runner, like the catalog and node loaders above: a bare
+              // dynamic import of a .js path does not resolve to the .ts source. The type below
+              // mirrors the module's real exports — tsc can't follow an ssrLoadModule path.
+              type PublishItem = { kind: string; name: string; why?: string; mode?: string };
+              type PublishModule = {
+                lintForPublish(rxHome: string, project: string): Promise<{ problems: unknown[]; errors: unknown[] }>;
+                collectProject(rxHome: string, project: string): unknown;
+                planPublish(collected: unknown, universe: string, token: string): Promise<Record<string, PublishItem[]>>;
+                sendPublish(plan: unknown, universe: string, token: string): Promise<{ sent: PublishItem[]; failed?: PublishItem[] }>;
+              };
+              const items = (await ssr(`${baseSrc}/items/publish.ts`)) as PublishModule;
+              const rxHome = resolve(projectRoot, "rx");
+
+              // LINT FIRST, ALWAYS. Nothing leaves the machine until the rules pass: a
+              // developer should learn about a raw hex value here, not from an HTTP error.
+              const { problems, errors } = await items.lintForPublish(rxHome, project);
+              if (errors.length) return json(res, { blocked: true, problems, errors });
+
+              const collected = items.collectProject(rxHome, project);
+              const plan = await items.planPublish(collected, universe, token);
+
+              // The screen renders kinds and names. The plan carries every file's full
+              // contents, so sending it whole would push the entire project through the
+              // browser for a list, and again on send.
+              type Lean = { kind: string; name: string; why?: string; mode?: string };
+              const lean = (list: Lean[] = []) =>
+                list.map(({ kind, name, why, mode }) => ({ kind, name, why, mode }));
+              const leanPlan = Object.fromEntries(
+                Object.entries(plan as Record<string, Lean[]>).map(([k, v]) => [k, lean(v)]),
+              );
+
+              if (path === "/publish/plan") return json(res, { problems, plan: leanPlan });
+
+              const result = await items.sendPublish(plan, universe, token);
+              return json(res, {
+                problems,
+                plan: leanPlan,
+                sent: lean(result.sent),
+                failed: lean(result.failed),
+              });
+            }
+
+            case path === "/dev/orgs":
+              return json(res, { orgs: c.themeOrgs() });
+
+            /**
+             * NEW PROJECT. The only thing Studio writes to disk that is not a definition.
+             *
+             * A project was previously creatable only by `bin/studio.mjs` at launch, and
+             * only when the folder was empty: it could make your first and never your
+             * second. A developer wanting another had to quit Studio and mkdir, which is
+             * the same "a tool telling you to do the thing it could do" that scaffolding
+             * was added to end.
+             *
+             * The CLI calls the SAME function (local/scaffold.mjs), so project one and
+             * project five are identical.
+             */
+            case path === "/dev/projects" && req.method === "POST": {
+              const { createProject } = await import("./scaffold.mjs");
+              const name = String((await body()).name ?? "");
+              try {
+                createProject(projectRoot, name);
+              } catch (e) {
+                // A bad name or an existing folder is the developer's to fix, not a fault:
+                // 400 so the dialog can say what is wrong beside the field.
+                return json(res, { error: e instanceof Error ? e.message : String(e) }, 400);
+              }
+              return json(res, { name });
+            }
+
+            case path === "/dev/themes":
+              return json(res, { themes: c.listThemeNames(org ?? c.DEFAULT_ORG) });
+
+            case path === "/dev/components":
+              return json(res, {
+                components: c.listDefinitions("component", org).map((d) => {
+                  const def = d as { name: string; props?: unknown };
+                  return { ...def, inputs: c.inputPropKeys(def.props), states: c.listStates("component", def.name) };
+                }),
+              });
+
+            case path === "/dev/templates":
+              return json(res, { templates: c.listTemplatesForWorkbench(org) });
+
+            case path === "/dev/atoms":
+              return json(res, { atoms: c.listDefinitions("atom") });
+
+            // The SDK renderer's two reads, served locally instead of over MCP.
+            case path === "/local/theme": {
+              const t = c.resolveTheme(url.searchParams.get("ref") ?? "light");
+              return t ? json(res, t) : json(res, { error: "theme not found" }, 404);
+            }
+            case path === "/local/definition": {
+              const uri = url.searchParams.get("uri") ?? "";
+              // Apps are addressed both ways (unoverse://apps/<org>/<id> and
+              // unoverse://templates/<org>/<id>); both load the template kind.
+              const kind = /\/(apps|templates)\//.test(uri) ? "template" : /\/atoms\//.test(uri) ? "atom" : "component";
+              const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "");
+              const d = c.loadDefinition(ref, kind);
+              return d ? json(res, d) : json(res, { error: `definition not found: ${uri}` }, 404);
+            }
+
+            case path === "/skills":
+              return json(res, { skills: readMarkdownLibrary(resolve(projectRoot, "prompts/skills")) });
+
+            case path.startsWith("/skills/"): {
+              const name = decodeURIComponent(path.slice("/skills/".length).replace(/\/file$/, ""));
+              const found = readMarkdownLibrary(resolve(projectRoot, "prompts/skills")).find((s) => s.name === name || s.id === name);
+              // SkillsView reads `d.skill`, matching the server's shape. Not the bare object.
+              return found ? json(res, { skill: found }) : json(res, { error: "skill not found" }, 404);
+            }
+
+            case path === "/prompt-blocks":
+              return json(res, { blocks: readMarkdownLibrary(resolve(projectRoot, "prompts/blocks")) });
+
+            // Registry toggles are a DEPLOYED concept: they persist to installed_plugins
+            // and decide what a running universe exposes. Local Studio has no database and
+            // no universe, so there is nothing to toggle. Report an empty state (the
+            // screens then fall back to their defaults) and accept writes as no-ops rather
+            // than erroring, so the shared screens need no local special-casing.
+            case path === "/registry/state":
+              if (req.method === "POST") return json(res, { ok: true });
+              return json(res, { entries: [] });
+
+            // ---- The developer's OWN nodes (their nodes/ folder). No marketplace. ----
+
+            case path === "/nodes": {
+              const n = await nodes();
+              if (!n) return json(res, { nodes: [], credentialTypes: [], reason: "no nodes/ folder in this project" });
+              return json(res, { nodes: n.list(), credentialTypes: n.credentialTypes() });
+            }
+
+            // Semantic ranking needs embeddings, which need a model and a key. Offline
+            // the screen already falls back to a local substring match on `ranked:false`,
+            // so say so honestly rather than pretending to rank.
+            case path === "/nodes/search":
+              return json(res, { ranked: false, nodes: [] });
+
+            // Which env variable each credential field reads from, and whether it is
+            // set. Names only, never values. Studio never WRITES a secret: keys live in
+            // the developer's own .env, which they already have and already gitignore.
+            case path === "/keys": {
+              const n = await nodes();
+              const types = (n?.credentialTypes() ?? []) as { name: string; properties?: { name: string }[] }[];
+              return json(res, { present: keyPresence(projectRoot, types) });
+            }
+
+            // Run one node against mock inputs, with the developer's own keys read
+            // from disk here (they never travel to the browser).
+            case path === "/execute" && req.method === "POST": {
+              const n = await nodes();
+              if (!n) return json(res, { error: "no nodes/ folder in this project" }, 404);
+              const b = await body();
+              const types = n.credentialTypes() as { name: string; properties?: { name: string }[] }[];
+              const keys = credentialsFromEnv(projectRoot, types);
+              try {
+                const out = await n.execute(String(b.nodeType), b.inputs ?? {}, b.config ?? {}, {
+                  // The execution context a node reads its credentials from. Local
+                  // testing only: one developer, one machine, their own keys.
+                  credentials: keys,
+                  workflowId: "studio-local",
+                  executionId: `local-${Date.now()}`,
+                });
+                return json(res, out ?? {});
+              } catch (err) {
+                // A failing node is the normal case while developing one. Report it as
+                // a result to display, not as a broken tool.
+                return json(res, { error: (err as Error).message, stack: (err as Error).stack }, 200);
+              }
+            }
+
+            default:
+              return next();
+          }
+        } catch (err) {
+          server.config.logger.error(`[studio] ${path}: ${(err as Error).message}`);
+          return json(res, { error: (err as Error).message }, 500);
+        }
+      });
+    },
+
+    /**
+     * Definitions are fetched at runtime, so Vite never sees them in the module graph.
+     * Watch the developer's rx/ and prompts/ and force a reload on any change: edit in
+     * your IDE, Studio updates. This is the same watcher the old coupled studio had.
+     */
+    handleHotUpdate({ server, file }) {
+      const watched = [resolve(projectRoot, "rx"), resolve(projectRoot, "prompts")];
+      if (watched.some((w) => file.startsWith(w))) {
+        server.ws.send({ type: "full-reload" });
+        return [];
+      }
+    },
+
+    configResolved() {
+      // Surface a clear failure at startup rather than an empty catalog later.
+      if (projectRoot && !existsSync(resolve(projectRoot, "rx"))) {
+        throw new Error(`No rx/ folder at ${projectRoot}`);
+      }
+      if (projectRoot) statSync(resolve(projectRoot, "rx"));
+    },
+  };
+}

package/local/scaffold.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Types for scaffold.mjs, which is plain ESM because `bin/studio.mjs` runs unbuilt and
+ * cannot transpile TypeScript. Same arrangement as the linters in `base`.
+ */
+
+/** Null when the name is usable, otherwise the reason to show beside the field. */
+export function checkProjectName(name: string): string | null;
+
+/** Create rx/<name>/ under `home`. Returns the created path. Throws if unusable. */
+export function createProject(home: string, name: string): string;
+
+/** The first project, plus prompts/ and nodes/ beside rx/. Returns the project path. */
+export function createFirstProject(home: string, name: string): string;

package/local/scaffold.mjs

@@ -0,0 +1,85 @@
+/**
+ * Creating a project, from either end.
+ *
+ * A project (an "org" in rx terms) is `rx/<name>/` holding components, styles and
+ * templates. It is the unit a developer authors in and the unit that publishes: every row
+ * that lands in a universe carries its name in the `org` column.
+ *
+ * ONE IMPLEMENTATION, TWO CALLERS. `bin/studio.mjs` creates the FIRST project at launch,
+ * when there is nowhere to click; the Studio UI creates every one after that. Written
+ * twice, they would drift, and the difference would be invisible: two projects that look
+ * alike and disagree about what a starting component contains. So this file is plain ESM
+ * rather than TypeScript, because the CLI runs unbuilt and cannot transpile.
+ *
+ * See docs/architecture/LOCAL_STUDIO.md.
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * A name that is safe as a folder AND legal as an item's `org`.
+ *
+ * Refuses rather than sanitises. Quietly turning "My Project" into "my-project" creates a
+ * folder the developer did not ask for and cannot find, and the name is about to travel
+ * into a database column and a primary key, where a surprise is expensive.
+ */
+export function checkProjectName(name) {
+  const n = String(name ?? "").trim();
+  if (!n) return "A name is required";
+  // RESERVED FIRST, so the message is the true reason. These folders under rx/ are never a
+  // developer's own project (collect.ts NOT_A_PROJECT), and a project named `marketplace`
+  // would shadow the design system in every loader that resolves one. Checked before the
+  // format rule because `_schema` fails that too, and "use lowercase letters" would send a
+  // developer off renaming when no name of that shape can ever be accepted.
+  if (["marketplace", "_schema", "orgs"].includes(n)) return `"${n}" is reserved`;
+  if (!/^[a-z][a-z0-9-]{1,38}$/.test(n))
+    return "Use lowercase letters, numbers and dashes, starting with a letter (2 to 39 characters)";
+  return null;
+}
+
+/** The component Studio opens on, so a new project is never an empty screen. */
+const WELCOME = [
+  "unoverse: '1.0'",
+  "kind: component",
+  "name: Welcome",
+  "category: Content",
+  "description: A first component. Edit this file and Studio updates as you save.",
+  "root:",
+  "  type: Stack",
+  "  style: { gap: '4', padding: '6' }",
+  "  children:",
+  "    - type: Text",
+  "      value: Hello from your first component",
+  "      style: { fontSize: 'lg', color: 'text.primary' }",
+  "",
+].join("\n");
+
+/**
+ * Create `rx/<name>/` under `home`, with its three authoring folders and one component.
+ *
+ * Refuses an existing name rather than merging into it: "create" that silently adopts a
+ * folder is how a developer ends up publishing someone else's work under their own project.
+ */
+export function createProject(home, name) {
+  const bad = checkProjectName(name);
+  if (bad) throw new Error(bad);
+
+  const root = join(home, "rx", name);
+  if (existsSync(root)) throw new Error(`rx/${name} already exists`);
+
+  for (const d of ["components/welcome", "templates", "styles"]) mkdirSync(join(root, d), { recursive: true });
+  writeFileSync(join(root, "components/welcome/welcome.yaml"), WELCOME);
+  return root;
+}
+
+/**
+ * The FIRST project, plus the folders that live beside rx/ rather than inside it.
+ *
+ * Skills, prompt blocks and nodes are per-developer and not per-project, so they are made
+ * once here and never by `createProject`.
+ */
+export function createFirstProject(home, name) {
+  const root = createProject(home, name);
+  for (const d of ["prompts/skills", "prompts/blocks", "nodes"]) mkdirSync(join(home, d), { recursive: true });
+  return root;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@unoverse-platform/studio",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "prepack": "node scripts/vendor-sdk.mjs"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@unoverse-platform/base": "^0.2.0",
+    "@unoverse-platform/marketplace": "*",
+    "@vitejs/plugin-react": "^4.3.4",
+    "oidc-client-ts": "^3.4.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-oidc-context": "^3.1.0",
+    "tailwindcss": "^4.0.0",
+    "vite": "^6.0.0"
+  },
+  "license": "MIT",
+  "bin": {
+    "unoverse-studio": "./bin/studio.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "screens",
+    "local",
+    "vendor",
+    "public",
+    "index.html",
+    "vite.config.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}