@unoverse-platform/studio 0.1.0

package/bin/studio.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * unoverse-studio — the authoring tool, run from a developer's own project.
+ *
+ * Studio is a TOOL, not a starter kit. A developer's repository holds only their assets
+ * (rx/, prompts/, nodes/); this is installed alongside and reads them. That is why there
+ * is no second repository to keep in step, and why their project contains no Docker, no
+ * ansible and no platform source.
+ *
+ * IT RUNS VITE, DELIBERATELY. Studio's file-reading host is a Vite plugin that loads the
+ * universe server's own disk loaders (local/plugin.ts, local/catalog.ts) rather than
+ * reimplementing them. Reproducing that in a bespoke server would fork those readers and
+ * they would drift apart within weeks, which is the exact problem local Studio was built
+ * to avoid. So the tool starts the same dev server `npm run dev` does.
+ *
+ * No database, no Redis, no engine, no Docker, and no account: those belong to running a
+ * universe, which is a different job. See docs/architecture/LOCAL_STUDIO.md.
+ */
+import { createServer } from "vite";
+import { dirname, resolve, join } from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
+import { createInterface } from "readline/promises";
+import { createFirstProject, checkProjectName } from "../local/scaffold.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const appRoot = resolve(here, "..");
+
+/**
+ * A project, if there is not one here yet.
+ *
+ * Studio USED to fail with "No rx/ folder found. Create rx/<your-project>/ to start one",
+ * which is a tool telling you to do the thing it could do. The first thirty seconds of a
+ * new install should end with something on screen, not with a mkdir.
+ *
+ * It asks rather than assumes: creating folders in whatever directory somebody happens to
+ * be in is not a thing to do quietly. Answer no and the original message stands.
+ */
+/** The same walk `catalog.ts` does: the nearest folder above us holding rx/. */
+function findProjectRootFromCwd() {
+  for (let dir = process.cwd(); ; ) {
+    if (existsSync(join(dir, "rx"))) return dir;
+    if (existsSync(join(dir, "apps/unoverse/rx"))) return join(dir, "apps/unoverse");
+    const parent = resolve(dir, "..");
+    if (parent === dir) return process.cwd();
+    dir = parent;
+  }
+}
+
+async function scaffoldIfEmpty() {
+  const cwd = process.cwd();
+  // The same walk findProjectRoot does. A project ABOVE us is a project; do not offer to
+  // make a second one inside it.
+  for (let dir = cwd; ; ) {
+    if (existsSync(join(dir, "rx")) || existsSync(join(dir, "apps/unoverse/rx"))) return;
+    const parent = resolve(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  console.log(`\n  No project here yet.\n\n  ${cwd}\n`);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  // Ask until the name is usable. It becomes a folder AND an item's `org` column, so a
+  // rejection here is cheaper than a rename after something has been published.
+  let name;
+  for (;;) {
+    name = (await rl.question("  Name your project [my-project]: ")).trim() || "my-project";
+    const bad = checkProjectName(name);
+    if (!bad) break;
+    console.log(`  ${bad}\n`);
+  }
+  rl.close();
+
+  // The same call the UI's New project makes, so the first project and the fifth are
+  // identical (local/scaffold.mjs).
+  createFirstProject(cwd, name);
+  console.log(`\n  Created rx/${name}/, prompts/ and nodes/\n`);
+}
+
+await scaffoldIfEmpty();
+
+/**
+ * POINT `base` AT THIS DEVELOPER'S PROJECT, before anything imports it.
+ *
+ * `paths.ts` snapshots its exports at import time (`export const RX_HOME = paths.rx`), so
+ * `setPaths()` called later updates an object nobody reads any more. The only hook that
+ * lands is the environment, read by `findHome()` on first import.
+ *
+ * Without this Studio fell back to walking up for `apps/unoverse`, so it worked perfectly
+ * in the monorepo it was written in and read the WRONG FOLDER everywhere else: a developer
+ * who had just created a project was shown the monorepo's. Silent, because both are valid
+ * directories and nothing errors.
+ */
+const projectRoot = findProjectRootFromCwd();
+process.env.UNOVERSE_HOME = projectRoot;
+console.log(`\n  Studio reading: ${join(projectRoot, "rx")}\n`);
+
+const server = await createServer({
+  // The APP is the vite root; the developer's project is found by walking up from the
+  // working directory (findProjectRoot), so Studio works from anywhere inside it.
+  root: appRoot,
+  configFile: resolve(appRoot, "vite.config.ts"),
+  // NO PORT OPTION. Studio is always 4108 (vite.config.ts, with strictPort), so the
+  // address in your browser's history is always the right one. A --port flag existed
+  // briefly and only produced sessions on 4117, 4118 and 4119 that nobody could find again.
+  server: { open: true },
+  // A tool should be quiet unless something is wrong.
+  logLevel: "warn",
+});
+
+await server.listen();
+
+const url = server.resolvedUrls?.local?.[0] ?? `http://localhost:${server.config.server.port}`;
+console.log(`\n  unoverse studio  ${url}\n`);
+
+// Ctrl-C should stop the server rather than leave a listener holding the port, which is
+// the thing that makes the next start fail with a confusing "port in use".
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, async () => {
+    await server.close();
+    process.exit(0);
+  });
+}

package/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>unoverse studio</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/local/catalog.ts

@@ -0,0 +1,105 @@
+/**
+ * The LOCAL catalog: the same disk loaders the universe server uses, pointed at the
+ * developer's own project folder instead of a running platform.
+ *
+ * This is the whole reason local Studio needs no backend. `definitions.ts` and
+ * `theme.ts` are pure filesystem readers: no Postgres, no Redis, no engine. So local
+ * Studio does not reimplement them (a second loader would drift within weeks, which is
+ * the exact problem this migration exists to fix). It imports the SAME modules and sets
+ * RX_PATH to the developer's folder before they load.
+ *
+ * See docs/architecture/LOCAL_STUDIO.md.
+ */
+import { resolve } from "path";
+import { existsSync } from "fs";
+
+/** The server's loader modules, loaded lazily so RX_PATH is set before they read it. */
+type Loaders = {
+  listDefinitions: (kind: string, org?: string) => unknown[];
+  listStates: (kind: string, name: string) => unknown[];
+  listTemplatesForWorkbench: (org?: string) => unknown[];
+  loadDefinition: (ref: string, kind: string) => unknown;
+  listOrgs: () => string[];
+  inputPropKeys: (props: unknown) => string[];
+  themeOrgs: () => string[];
+  listThemeNames: (org: string) => string[];
+  resolveTheme: (name: string) => unknown;
+  DEFAULT_ORG: string;
+};
+
+/**
+ * Resolve the developer's project root: the folder holding `rx/`. Walks up from the
+ * working directory so `unoverse studio` works from anywhere inside the project, the
+ * same way git and npm behave. Throws rather than guessing, because silently reading
+ * the wrong folder is worse than not starting.
+ */
+export function findProjectRoot(from: string = process.cwd()): string {
+  let dir = resolve(from);
+  for (;;) {
+    // A developer's project (starter kit): rx/ sits at the root.
+    if (existsSync(resolve(dir, "rx"))) return dir;
+    // This monorepo, where Studio's author works: rx/ lives under apps/unoverse. Same
+    // shape underneath (rx/ + prompts/), just nested, so return that as the root.
+    if (existsSync(resolve(dir, "apps/unoverse/rx"))) return resolve(dir, "apps/unoverse");
+    const parent = resolve(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `No rx/ folder found in ${from} or any parent. Run Studio from inside your project, ` +
+      `or create rx/<your-project>/ to start one.`,
+  );
+}
+
+/**
+ * Load the server's disk loaders with RX_PATH pointed at this project.
+ *
+ * `baseSrc` is the path to @unoverse-platform/base's src, and `load` is Vite's
+ * ssrLoadModule (the dev server transpiles the TypeScript for us, so local Studio needs no
+ * build step of its own).
+ *
+ * THESE USED TO COME OUT OF apps/unoverse/server/src, which is what kept Studio from being
+ * publishable: nothing installed from npm can reach into another app's source. They live in
+ * `base` now, so Studio's entire platform dependency is one package.
+ */
+export async function loadCatalog(
+  baseSrc: string,
+  load: (id: string) => Promise<Record<string, unknown>>,
+  projectRoot: string,
+): Promise<Loaders> {
+  /**
+   * POINT `base` AT THIS DEVELOPER'S PROJECT, before any loader is imported.
+   *
+   * This used to set `process.env.RX_PATH`, which paths.ts no longer reads: it was
+   * rewritten around UNOVERSE_HOME and `setPaths()`. The variable was simply ignored, and
+   * because paths.ts falls back to walking up for `apps/unoverse`, Studio kept working in
+   * THIS monorepo and read the wrong folder everywhere else. It served the monorepo's own
+   * projects to a developer who had just created one of their own.
+   *
+   * Silent because both answers are valid directories. Nothing errors; the wrong content
+   * simply appears, which is the failure mode this whole tool exists to avoid.
+   *
+   * ORDER MATTERS. paths.ts resolves its named exports ONCE at import ("a host calling
+   * setPaths() must do it before anything else imports this module"), so this load happens
+   * first and every later import sees the developer's home.
+   */
+  const paths = await load(resolve(baseSrc, "paths.ts"));
+  (paths.setPaths as (n: { home: string }) => void)({ home: projectRoot });
+
+  const defs = await load(resolve(baseSrc, "definitions/definitions.ts"));
+  const theme = await load(resolve(baseSrc, "definitions/theme.ts"));
+  const inputs = await load(resolve(baseSrc, "definitions/inputs.ts"));
+
+  return {
+    listDefinitions: defs.listDefinitions as Loaders["listDefinitions"],
+    listStates: defs.listStates as Loaders["listStates"],
+    listTemplatesForWorkbench: defs.listTemplatesForWorkbench as Loaders["listTemplatesForWorkbench"],
+    loadDefinition: defs.loadDefinition as Loaders["loadDefinition"],
+    listOrgs: defs.listOrgs as Loaders["listOrgs"],
+    inputPropKeys: inputs.inputPropKeys as Loaders["inputPropKeys"],
+    themeOrgs: theme.themeOrgs as Loaders["themeOrgs"],
+    listThemeNames: theme.listThemeNames as Loaders["listThemeNames"],
+    resolveTheme: theme.resolveTheme as Loaders["resolveTheme"],
+    DEFAULT_ORG: theme.DEFAULT_ORG as string,
+  };
+}

package/local/keys.ts

@@ -0,0 +1,118 @@
+/**
+ * Keys for local node testing: read from the project's own `.env`.
+ *
+ * Deliberately NOT a Studio-specific credential store. Developers already have a
+ * `.env`, it is already gitignored, and the platform already reads one. A second secret
+ * file would be a new concept to learn, a new thing to leak, and a new thing to explain.
+ *
+ * Studio therefore never WRITES a secret. It reads `.env` (and `.env.local`, which wins),
+ * tells the developer the exact variable each credential field wants, and reports whether
+ * it is set. Entering the value happens in the editor they are already in.
+ *
+ * Naming: the credential name loses its `Credential` suffix and the field is upper
+ * snake-cased, so `airtableCredential.personalAccessToken` reads from
+ * `AIRTABLE_PERSONAL_ACCESS_TOKEN`.
+ *
+ * See docs/architecture/LOCAL_STUDIO.md.
+ */
+import { resolve } from "path";
+import { existsSync, readFileSync } from "fs";
+
+/** camelCase or PascalCase to UPPER_SNAKE. */
+function upperSnake(s: string): string {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[-\s]+/g, "_")
+    .toUpperCase();
+}
+
+/**
+ * The env variable a credential field reads from.
+ *
+ * The credential's own name is treated as ONE word, so `openAICredential` gives
+ * `OPENAI_API_KEY` rather than `OPEN_AI_API_KEY`. That matters: the provider names
+ * developers already have in their .env are the ones we should be reading.
+ * `envVarCandidates` keeps the split form working too, so neither spelling is a trap.
+ */
+export function envVarFor(credentialName: string, field: string): string {
+  const base = credentialName.replace(/Credentials?$/i, "");
+  return `${base.toUpperCase()}_${upperSnake(field)}`;
+}
+
+/** Accepted spellings, most conventional first. */
+export function envVarCandidates(credentialName: string, field: string): string[] {
+  const base = credentialName.replace(/Credentials?$/i, "");
+  const compact = `${base.toUpperCase()}_${upperSnake(field)}`;
+  const split = `${upperSnake(base)}_${upperSnake(field)}`;
+  return compact === split ? [compact] : [compact, split];
+}
+
+/**
+ * Parse the project's env files. `.env.local` overrides `.env`, matching the convention
+ * every other tool uses. Deliberately tolerant: a malformed line is skipped, never fatal.
+ */
+export function readEnv(projectRoot: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const name of [".env", ".env.local"]) {
+    // Look in the project AND its parent: in a monorepo the .env usually sits at the root.
+    for (const dir of [resolve(projectRoot, ".."), projectRoot]) {
+      const f = resolve(dir, name);
+      if (!existsSync(f)) continue;
+      for (const line of readFileSync(f, "utf8").split("\n")) {
+        const t = line.trim();
+        if (!t || t.startsWith("#")) continue;
+        const i = t.indexOf("=");
+        if (i <= 0) continue;
+        const key = t.slice(0, i).trim();
+        let value = t.slice(i + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+          value = value.slice(1, -1);
+        }
+        if (value) out[key] = value;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Build the credential object a node executor expects, from env.
+ * Shape mirrors the platform's: { <credentialName>: { <field>: value } }.
+ */
+export function credentialsFromEnv(
+  projectRoot: string,
+  types: { name: string; properties?: { name: string }[] }[],
+): Record<string, Record<string, string>> {
+  const env = readEnv(projectRoot);
+  const out: Record<string, Record<string, string>> = {};
+  for (const t of types) {
+    const fields: Record<string, string> = {};
+    for (const p of t.properties ?? []) {
+      const v = envVarCandidates(t.name, p.name).map((n) => env[n]).find(Boolean);
+      if (v) fields[p.name] = v;
+    }
+    if (Object.keys(fields).length) out[t.name] = fields;
+  }
+  return out;
+}
+
+/**
+ * Which env variable each credential field wants, and whether it is currently set.
+ * Names only, never values: the browser has no reason to see a secret.
+ */
+export function keyPresence(
+  projectRoot: string,
+  types: { name: string; properties?: { name: string }[] }[],
+): Record<string, { field: string; env: string; set: boolean }[]> {
+  const env = readEnv(projectRoot);
+  const out: Record<string, { field: string; env: string; set: boolean }[]> = {};
+  for (const t of types) {
+    out[t.name] = (t.properties ?? []).map((p) => {
+      const names = envVarCandidates(t.name, p.name);
+      // Report whichever spelling the developer actually used, else the conventional one.
+      const used = names.find((n) => env[n]);
+      return { field: p.name, env: used ?? names[0], set: Boolean(used) };
+    });
+  }
+  return out;
+}

package/local/nodes.ts

@@ -0,0 +1,77 @@
+/**
+ * The LOCAL node catalog and runner.
+ *
+ * Scope (decided 2026-07-25): the developer's OWN nodes only, the ones in their
+ * project's `nodes/` folder. Local Studio never reads the installed plugins directory,
+ * `installed_plugins`, or the marketplace. Acquiring a node is a universe's job; this
+ * is developing the nodes you are writing.
+ *
+ * As with the definitions (catalog.ts), this reuses the server's REAL registration
+ * path rather than scraping source: each package is loaded through `loadPlugin`, which
+ * calls its `setup(api)` exactly as production does. So what Studio lists is what the
+ * platform would register, including config schemas and credential types.
+ *
+ * The bootstrap comment is explicit that this path touches neither Redis nor the
+ * workflow service, which is what makes it usable with no backend.
+ *
+ * See docs/architecture/LOCAL_STUDIO.md.
+ */
+import { resolve } from "path";
+import { existsSync } from "fs";
+
+export interface LocalNodes {
+  list: () => unknown[];
+  credentialTypes: () => unknown[];
+  /** Argument order mirrors the server's executeNode(nodeType, inputs, config, context). */
+  execute: (type: string, inputs: unknown, config: unknown, context: unknown) => Promise<unknown>;
+}
+
+/**
+ * Load the developer's node packages into the in-memory registry.
+ *
+ * `projectRoot` is the folder holding `nodes/`. Returns null when there is no nodes/
+ * folder at all, so Studio can simply omit the section rather than showing an error:
+ * plenty of developers only author design assets.
+ */
+export async function loadLocalNodes(
+  baseSrc: string,
+  load: (id: string) => Promise<Record<string, unknown>>,
+  projectRoot: string,
+): Promise<LocalNodes | null> {
+  const nodesDir = resolve(projectRoot, "nodes");
+  if (!existsSync(nodesDir)) return null;
+
+  // Set BEFORE the modules load: paths.ts reads process.env at module load time.
+  process.env.NODES_PATH = nodesDir;
+
+  const discovery = await load(resolve(baseSrc, "plugins/discovery.ts"));
+  const loader = await load(resolve(baseSrc, "plugins/loader.ts"));
+  const platform = await load(resolve(baseSrc, "platform/index.ts"));
+  const registry = await load(resolve(baseSrc, "registry.ts"));
+  const executor = await load(resolve(baseSrc, "executor.ts"));
+
+  const api = (platform.createNodeServiceAPI as () => unknown)();
+  const packages = (discovery.discoverNodesHome as () => string[])();
+
+  for (const name of packages) {
+    try {
+      await (loader.loadPlugin as (n: string, a: unknown) => Promise<string[]>)(name, api);
+    } catch (err) {
+      // One broken package must never stop the others loading. Same posture as the
+      // server's bootstrap, and the same reason: a bad asset cannot take the tool down.
+      console.warn(`[studio] could not load node package ${name}: ${(err as Error).message}`);
+    }
+  }
+
+  return {
+    list: () => (registry.getAllNodes as () => unknown[])(),
+    credentialTypes: () => (registry.getAllCredentialTypes as () => unknown[])(),
+    execute: async (type, inputs, config, context) =>
+      (executor.executeNode as (t: string, i: unknown, c: unknown, ctx: unknown) => Promise<unknown>)(
+        type,
+        inputs,
+        config,
+        context,
+      ),
+  };
+}