unoverse 0.1.68 → 0.1.70

package/bin/unoverse.mjs

@@ -11,7 +11,7 @@ import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { create } from "../lib/create.mjs";
+import { create } from "../lib/create/index.mjs";
 
 /**
  * ONE BINARY. There is no `./unoverse` any more.

package/lib/create/credential.mjs

@@ -0,0 +1,90 @@
+/**
+ * The registry credential: whatever shape it arrives in, and whether it actually works.
+ *
+ * Two hard-won rules live here. A credential is a PAIR (the downloaded Docker credentials
+ * file carries base64("email:token"), so the username is the account email, not the
+ * token). And the only honest validation is the operation itself: probing with a
+ * different check once approved a credential that `docker login` then refused.
+ */
+import { spawnSync } from "node:child_process";
+
+export const REGISTRY_HOST = "registry.digitalocean.com";
+
+/** Operators hold the credential in two shapes: the raw dop_v1 API token, and the
+ * pre-encoded base64 `user:token` blob that docker config (and the starter's own
+ * `docr` setting) uses. Wrapping the second shape in base64 AGAIN is how a valid
+ * credential gets refused, so detect it and pass it through untouched. */
+/** The raw dop_v1 token, whichever shape was pasted. docker login needs the raw form,
+ * so the base64 user:token blob is decoded before anything downstream sees it. */
+/** The credential AS A PAIR. The downloaded Docker credentials file carries
+ * base64("email:token") — the username is the ACCOUNT EMAIL, and logging in with the
+ * token as username (right for API tokens) gets "unauthorized" for it. So nothing here
+ * reduces to a bare token any more: whatever shape is pasted, the exact user:password
+ * pair comes out and is used verbatim.
+ *   raw dop_v1            → token:token
+ *   base64("u:p")         → u:p          (email:token, or :token → token:token)
+ *   the whole JSON file   → its auth value, decoded the same way
+ */
+export function parseCredential(input) {
+  const t = input.trim().replace(/^["']|["']$/g, "");
+  const pair = (d) => {
+    const m = /^([\x20-\x7e]*):([\x20-\x7e]+)$/.exec(d);
+    return m ? { user: m[1] || m[2], pass: m[2] } : null;
+  };
+  const auth = /"auth"\s*:\s*"([A-Za-z0-9+/=]+)"/.exec(t);
+  if (auth) {
+    const p = pair(Buffer.from(auth[1], "base64").toString("utf8"));
+    if (p) return p;
+  }
+  if (/^[A-Za-z0-9+/]+=*$/.test(t)) {
+    const p = pair(Buffer.from(t, "base64").toString("utf8"));
+    if (p) return p;
+  }
+  const inline = /dop_v1_[0-9a-f]{64}/.exec(t);
+  if (inline) return { user: inline[0], pass: inline[0] };
+  return { user: t, pass: t };
+}
+
+
+function registryAuth(cred) {
+  return Buffer.from(`${cred.user}:${cred.pass}`).toString("base64");
+}
+
+/** The gate: prove the token opens the registry before handing over the kit.
+ * Docker registries use the bearer-realm flow: /v2/ answers 401 and names the
+ * auth realm; presenting the token there yields 200 (valid) or 401 (refused). */
+export async function validateRegistryToken(cred) {
+  try {
+    const probe = await fetch(`https://${REGISTRY_HOST}/v2/`);
+    const wa = probe.headers.get("www-authenticate") ?? "";
+    const realm = /realm="([^"]+)"/.exec(wa)?.[1];
+    const service = /service="([^"]+)"/.exec(wa)?.[1] ?? REGISTRY_HOST;
+    if (!realm) return probe.status === 200;
+    const res = await fetch(
+      `${realm}?service=${encodeURIComponent(service)}&scope=registry:catalog:*`,
+      { headers: { Authorization: `Basic ${registryAuth(cred)}` } },
+    );
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export function dockerUp() {
+  return spawnSync("docker", ["info"], { stdio: "ignore" }).status === 0;
+}
+
+/** The ONLY honest validation is the operation itself. create used to probe the auth
+ * realm with its own HTTP call and say "token accepted", then docker login failed on
+ * the same credential two minutes later — the tool approving a token with a weaker
+ * check than the one that counts. When Docker is up, validation IS docker login (and
+ * the credential lands in the keychain, so nothing downstream logs in again). */
+export function dockerLogin(cred) {
+  const r = spawnSync("docker", ["login", REGISTRY_HOST, "-u", cred.user, "--password-stdin"], {
+    input: cred.pass,
+    encoding: "utf8",
+  });
+  const err = (r.stderr || "").split("\n").filter((l) => l && !/^WARNING/i.test(l)).pop() || "";
+  return { ok: r.status === 0, err };
+}
+

package/lib/create/download.mjs

@@ -0,0 +1,19 @@
+/**
+ * The starter tree, fetched from the public template repo.
+ */
+import { mkdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+export const STARTER_TARBALL =
+  "https://codeload.github.com/unoverse-platform/starter/tar.gz/refs/heads/main";
+
+export function download(dir, stripComponents = 1, filter = "") {
+  mkdirSync(dir, { recursive: true });
+  const r = spawnSync(
+    "sh",
+    ["-c", `curl -fsSL '${STARTER_TARBALL}' | tar -xz --strip-components=${stripComponents} -C '${dir}' ${filter}`],
+    { stdio: ["ignore", "inherit", "inherit"] },
+  );
+  if (r.status !== 0) throw new Error("download failed");
+}
+

package/lib/create/index.mjs

@@ -0,0 +1,141 @@
+/**
+ * `unoverse create` — first contact, as a question instead of a repo choice.
+ *
+ * Studio is the default path: most people author, few people operate. A universe is the
+ * operator tier and is GATED on a working registry credential, because the kit is useless
+ * without one. The steps it owns are the ORDER of the conversation; the work each step
+ * does lives beside it (credential, target, download) and the terminal dressing in ../ui.
+ */
+import { createInterface } from "node:readline/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+import { cyan, dim, ok, fail, ask, select } from "../ui.mjs";
+import { parseCredential, validateRegistryToken, dockerUp, dockerLogin } from "./credential.mjs";
+import { resolveTarget, label } from "./target.mjs";
+import { download } from "./download.mjs";
+
+export async function create(nameArg) {
+  console.log(`\n  ${cyan("⬡ What are you building?")}\n`);
+  const choice = String((await select()) + 1);
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+
+    if (choice === "1") {
+      console.log(`\n  ${dim("Launching Unoverse Studio. It creates and manages your projects.")}\n`);
+      rl.close();
+      const r = spawnSync("npx", ["-y", "@unoverse-platform/studio@latest"], { stdio: "inherit" });
+      process.exit(r.status ?? 0);
+    }
+
+    if (choice === "2") {
+      // ALREADY A UNIVERSE? Then this is a re-run, not a conflict. The first create
+      // scaffolds the files; if setup was interrupted (Ctrl-C at any question), running
+      // create again used to refuse with "this folder is not empty" — which reads as
+      // broken when the folder holds exactly what create itself put there. A universe is
+      // recognized by its compose file; resume setup instead.
+      const target = nameArg || ".";
+      if (existsSync(`${target}/docker-compose.yml`)) {
+        console.log(`\n  ${dim(`${target === "." ? "This folder" : `./${target}`} is already a universe. Picking setup back up.`)}\n`);
+        rl.close();
+        const here2 = dirname(fileURLToPath(import.meta.url));
+        const vend = resolve(here2, "../operator/operator.sh");
+        const op = existsSync(vend) ? vend : resolve(here2, "../../../scripts/operator.sh");
+        const r2 = spawnSync("bash", [op, "init"], { stdio: "inherit", cwd: target });
+        process.exit(r2.status ?? 0);
+      }
+
+      // TARGET FIRST, credential second. This used to ask for the registry token, make a
+      // network round-trip to validate it, and only then discover the folder was not
+      // empty. Never ask for a credential you are about to throw away.
+      const name = resolveTarget(nameArg);
+
+      console.log(`\n  ${cyan("A universe needs a registry access token.")}`);
+      console.log(`  ${dim("It authorizes the platform's images. Your Unoverse admin issues it.")}\n`);
+      const useDocker = dockerUp();
+      let token;
+      // A refused token re-asks RIGHT HERE. Being thrown out of the wizard to run
+      // create again is its own bug.
+      for (;;) {
+        token = parseCredential(await ask(rl, "Registry access token: "));
+        if (!token.pass) {
+          fail("no token. The universe kit is available to licensed operators");
+          process.exit(1);
+        }
+        process.stdout.write("  validating against the registry...");
+        if (useDocker) {
+          const res = dockerLogin(token);
+          console.log("");
+          if (res.ok) { ok("token accepted"); break; }
+          fail("the registry refused it:");
+          console.log(`      ${dim(res.err)}`);
+          console.log(`  ${dim("Paste the credential exactly as your admin sent it (any shape works), or Ctrl-C to stop.")}\n`);
+        } else {
+          const valid = await validateRegistryToken(token);
+          console.log("");
+          if (valid) { ok("token accepted"); break; }
+          fail("that token was refused by the registry");
+          console.log(`  ${dim("Check it with your Unoverse admin, or Ctrl-C to stop.")}\n`);
+        }
+      }
+
+      download(name);
+      ok(`universe scaffolded in ${label(name)}`);
+
+      // CREATE FINISHES THE JOB. It used to stop here and tell you to go and run
+      // `./unoverse init`, which asked for this same token a second time. The token is
+      // already in hand and already validated, so hand it over and configure now.
+      rl.close();
+      console.log("");
+      // This package's own operator, run against the folder just scaffolded.
+      const here = dirname(fileURLToPath(import.meta.url));
+      const vendored = resolve(here, "../operator/operator.sh");
+      const operatorScript = existsSync(vendored)
+        ? vendored
+        : resolve(here, "../../../scripts/operator.sh");
+      // NO authoring skill here, deliberately. Building components, nodes and agent
+      // skills is STUDIO work and its skill ships with Studio projects. What a universe
+      // offers Claude Code is the canvas MCP (.mcp.json in the scaffold): building and
+      // managing workflows on this universe's Canvas.
+      const r = spawnSync("bash", [operatorScript, "init"], {
+        stdio: "inherit",
+        cwd: name,
+        env: { ...process.env, UNOVERSE_DOCR_TOKEN: token.pass, UNOVERSE_DOCR_USER: token.user },
+      });
+      if (r.status !== 0) {
+        fail(`setup did not finish. Run 'unoverse start'${name === "." ? "" : ` in ./${name}`} to pick it back up`);
+        process.exit(r.status ?? 1);
+      }
+      console.log(`
+  Next:${name === "." ? "" : `
+    cd ${name}`}
+    unoverse start
+
+  ${cyan("Build with Claude:")} open this folder in Claude Code and describe the
+  workflow you want. Claude builds and manages workflows live on this
+  universe's Canvas.
+
+  ${dim("Components, nodes and agent skills are built in Studio: unoverse studio")}
+  ${dim("How it works: https://github.com/unoverse-platform/docs")}
+`);
+      return;
+    }
+
+    if (choice === "3") {
+      const name = resolveTarget(nameArg);
+      // The reference client ships inside the starter — take just that folder.
+      download(name, 3, "'*/packages/client'");
+      ok(`client app scaffolded in ${label(name)}`);
+      console.log(`\n  Next:${name === "." ? "" : `\n    cd ${name}`}\n    npm install && npm run dev\n\n  ${cyan("Build with Claude:")} open this folder in Claude Code and describe what you want, in plain words.\n`);
+      return;
+    }
+
+    fail(`unknown choice: ${choice}`);
+    process.exit(1);
+  } finally {
+    rl.close();
+  }
+}

package/lib/create/target.mjs

@@ -0,0 +1,40 @@
+/**
+ * Which folder gets scaffolded, and whether it is safe to write into.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { dim, fail } from "../ui.mjs";
+
+/**
+ * Where to scaffold. NO NAME MEANS THE FOLDER YOU ARE STANDING IN.
+ *
+ * That is what a Studio project has always done (option 1 hands the cwd to Studio), so
+ * the other two paths agreeing removes a difference nobody could have guessed. Passing a
+ * name still makes a subfolder: `unoverse create acme` → ./acme.
+ *
+ * The old guard refused any target that EXISTED, which made "." impossible — the folder
+ * you are in always exists, so it failed with "./. already exists". Existence was never
+ * the question; whether there is anything to overwrite is. `.git` and `.DS_Store` do not
+ * count, so scaffolding into a folder you just `git init`ed works.
+ */
+export function resolveTarget(nameArg) {
+  const dir = nameArg || ".";
+  const here = dir === ".";
+  // DOTFILES DO NOT COUNT. A folder holding only .git, .claude, .vscode or .DS_Store is
+  // empty to the person standing in it: that is tool and editor config they had before
+  // they decided to build anything. Naming a few exceptions was not enough — a fresh
+  // folder opened in an editor already has .claude/ in it, and refusing that reads as
+  // the tool being broken.
+  const existing = existsSync(dir)
+    ? readdirSync(dir).filter((f) => !f.startsWith("."))
+    : [];
+  if (existing.length) {
+    fail(here ? "this folder is not empty" : `./${dir} is not empty`);
+    console.log(`  ${dim("Scaffolding would overwrite what is here. Use an empty folder, or pass a name.")}`);
+    process.exit(1);
+  }
+  return dir;
+}
+
+/** Human name for the target, for messages that should not say "./.". */
+export const label = (dir) => (dir === "." ? "this folder" : `./${dir}`);
+

package/lib/ui.mjs

@@ -0,0 +1,119 @@
+/**
+ * Terminal dressing, in one place.
+ *
+ * Colour helpers and the arrow-key list. They lived inside create.mjs, and urls.mjs kept
+ * a second copy of the colours; anything that asks a question wants the same list, so it
+ * lives beside them rather than inside whichever command needed it first.
+ */
+
+const COLOR = !process.env.NO_COLOR;
+const paint = (c) => (s) => (COLOR ? `\x1b[${c}m${s}\x1b[0m` : s);
+export const bold = paint("1");
+export const dim = paint("2");
+export const cyan = paint("36");
+export const green = paint("32");
+export const red = paint("31");
+export const ok = (s) => console.log(`  ${green("✓")} ${s}`);
+export const fail = (s) => console.log(`  ${red("✗")} ${s}`);
+
+/** One question, trimmed. */
+export async function ask(rl, q) {
+  return (await rl.question(`  ${q}`)).trim();
+}
+
+export const OPTIONS = [
+  ["Studio", "Components, agents and workflows", "Most people start here"],
+  ["Universe", "Run the platform yourself, on your own infrastructure"],
+  ["Client", "A client accelerator that talks to unoverse"],
+];
+const NAME_W = Math.max(...OPTIONS.map(([n]) => n.length)) + 3;
+// Lines the menu occupies, so a redraw knows how far up to go.
+const MENU_LINES = OPTIONS.reduce((n, [, , note]) => n + (note ? 2 : 1), 0);
+
+function renderMenu(active) {
+  OPTIONS.forEach(([name, desc, note], i) => {
+    const on = i === active;
+    process.stdout.write(
+      `\x1b[2K  ${on ? cyan("❯") : " "} ${i + 1}  ${on ? bold(name) : name}` +
+        `${" ".repeat(NAME_W - name.length)}${on ? desc : dim(desc)}\n`,
+    );
+    if (note) process.stdout.write(`\x1b[2K      ${" ".repeat(NAME_W + 1)}${dim(note)}\n`);
+  });
+}
+
+/**
+ * Pick one, with the arrow keys.
+ *
+ * NO DEPENDENCY. Raw stdin is all a list picker needs, and `packages/cli` is deliberately
+ * zero-dependency (it is the first thing anyone installs). Up/down move, a digit jumps,
+ * Enter takes it, Ctrl-C leaves without doing anything.
+ *
+ * NOT A TTY means something is piping input, so fall back to reading a line. A picker
+ * that only works interactively would break every scripted install.
+ */
+export function select() {
+  if (!process.stdin.isTTY) {
+    renderMenu(0);
+    process.stdout.write("\n  Choose 1, 2 or 3 (Enter for 1): ");
+    return new Promise((resolve) => {
+      let buf = "";
+      process.stdin.on("data", (d) => {
+        buf += d;
+        if (buf.includes("\n")) {
+          const n = parseInt(buf.trim(), 10);
+          resolve(Number.isInteger(n) && n >= 1 && n <= OPTIONS.length ? n - 1 : 0);
+        }
+      });
+      process.stdin.on("end", () => resolve(0));
+    });
+  }
+
+  return new Promise((resolve) => {
+    let active = 0;
+    process.stdout.write("\x1b[?25l"); // hide cursor while the list is live
+    renderMenu(active);
+    process.stdout.write(`\n  ${dim("↑↓ to move, Enter to choose")}`);
+
+    const redraw = () => {
+      process.stdout.write(`\x1b[${MENU_LINES + 1}A\r`);
+      renderMenu(active);
+      process.stdout.write(`\n  ${dim("↑↓ to move, Enter to choose")}`);
+    };
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    // PARSE the chunk, do not compare it. Keystrokes batch: hold a key down, or paste,
+    // and "\x1b[B\x1b[B\r" arrives as ONE data event. Comparing the whole chunk to a
+    // single key silently ignores every one of them.
+    const onKey = (buf) => {
+      const k = buf.toString();
+      let moved = false;
+      for (let i = 0; i < k.length; i++) {
+        if (k[i] === "\u0003") { done(); process.stdout.write("\n"); process.exit(130); }
+        if (k[i] === "\x1b" && k[i + 1] === "[" && (k[i + 2] === "A" || k[i + 2] === "B")) {
+          const step = k[i + 2] === "A" ? -1 : 1;
+          active = (active + step + OPTIONS.length) % OPTIONS.length;
+          moved = true;
+          i += 2;
+          continue;
+        }
+        if (k[i] === "\r" || k[i] === "\n") {
+          if (moved) redraw();
+          done();
+          process.stdout.write("\n\n");
+          return resolve(active);
+        }
+        if (/[1-9]/.test(k[i]) && +k[i] <= OPTIONS.length) { active = +k[i] - 1; moved = true; }
+      }
+      if (moved) redraw();
+    };
+    const done = () => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.off("data", onKey);
+      process.stdout.write("\x1b[?25h"); // cursor back
+    };
+    process.stdin.on("data", onKey);
+  });
+}
+

package/lib/urls.mjs

@@ -40,13 +40,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { spawnSync } from "node:child_process";
 
-const COLOR = !process.env.NO_COLOR;
-const paint = (code) => (s) => (COLOR ? `\x1b[${code}m${s}\x1b[0m` : s);
-const bold = paint("1");
-const dim = paint("2");
-const cyan = paint("36");
-const green = paint("32");
-const red = paint("31");
+import { bold, dim, cyan, green, red } from "./ui.mjs";
 
 /** Walk up from cwd to the folder holding .env.production (a universe checkout). */
 function findUniverseRoot() {