unoverse 0.1.154 → 0.1.156

package/bin/unoverse.mjs

@@ -59,8 +59,11 @@ const UNIVERSE = findUniverse();
 // and that refresh now belongs to `start --pull`.
 const OPERATOR_COMMANDS = new Set([
   "start", "stop", "check", "logs", "deploy", "destroy", "db-allow",
-  // kept working, not advertised
-  "ground", "dev", "build", "publish",
+  // kept working, not advertised. `publish` is NOT here: it has its own case below,
+  // because ONE VERB serves two lanes and the folder decides which (LOCAL_STUDIO.md
+  // §Publish is terminal-only) — an asset workspace publishes item rows, a universe
+  // publishes the platform via the operator.
+  "ground", "dev", "build",
 ]);
 
 const [, , cmd, ...args] = process.argv;
@@ -93,6 +96,8 @@ const HELP = [
   "",
   `  ${bold("After that")}`,
   row("studio", "Design components, nodes and agent skills"),
+  row("publish", "Ship your work to your universe"),
+  row("login", "Sign in to a universe (publish asks by itself when needed)"),
   row("update", "Update this CLI"),
   "",
 ].join("\n");
@@ -201,6 +206,48 @@ switch (cmd) {
     process.exit(r.status ?? 0);
   }
 
+  case "login": {
+    // Standalone sign-in. publish calls the same flow lazily, so this exists for
+    // "set up my machine" moments and for re-authenticating after a permissions change.
+    const { login, normaliseUrl } = await import("../lib/login.mjs");
+    let target = args[0];
+    if (!target) {
+      // No URL typed: the workspace's committed target is the obvious answer.
+      const { findWorkspace, readConfig } = await import("../lib/workspace.mjs");
+      const ws = findWorkspace();
+      if (ws?.kind === "assets") target = (await readConfig(ws.root)).universe;
+    }
+    if (!target) {
+      console.error(`\n  Which universe? unoverse login <url>\n  ${dim("(or run it from a workspace whose unoverse.yaml names one)")}\n`);
+      process.exit(1);
+    }
+    try {
+      await login(normaliseUrl(target));
+    } catch (e) {
+      console.error(`\n  ✗ ${e.message}\n`);
+      process.exit(1);
+    }
+    break;
+  }
+
+  case "publish": {
+    // ONE VERB, the folder decides (LOCAL_STUDIO.md §Publish is terminal-only).
+    // Nearest marker up from cwd: a design home → publish this workspace's items;
+    // a docker-compose.yml → publish is the operator's (the platform release lane).
+    const { findWorkspace } = await import("../lib/workspace.mjs");
+    const ws = findWorkspace();
+    if (ws?.kind === "assets") {
+      const { publish } = await import("../lib/publish.mjs");
+      await publish(args);
+    } else if (ws?.kind === "universe") {
+      operator({ root: ws.root, script: OPERATOR }, ["publish", ...args]);
+    } else {
+      console.log(`\n  Nothing to publish here: no design/ workspace and no universe above ${process.cwd()}.\n  Start one with: unoverse create\n`);
+      process.exit(1);
+    }
+    break;
+  }
+
   case "help":
   case "--help":
   case "-h":

package/lib/login.mjs

@@ -0,0 +1,274 @@
+/**
+ * unoverse login — the Stripe-shaped browser handshake.
+ *
+ * A UNIVERSE NAMES ITS OWN IDENTITY PROVIDER. Nothing here hardcodes an issuer or a
+ * vendor: the CLI asks the universe at /.well-known/unoverse-universe, then asks that
+ * issuer's own /.well-known/openid-configuration for its endpoints. Auth0, Cognito,
+ * Okta, Entra and Keycloak all answer the second document, which is why the flow is
+ * Authorization Code + PKCE with a loopback redirect and NOT the device flow (Cognito
+ * has no device flow; every OIDC provider has this).
+ *
+ * THE CALLBACK PORT IS FIXED (4109) because IdPs match redirect URIs exactly — an
+ * ephemeral port could never be registered. 4109 continues the platform's sequence
+ * (4105 public listener, 4106 runtime, 4107 unoverse-runtime, 4108 Studio) and is held
+ * only for the seconds the browser takes. ground.sh registers it as an allowed callback.
+ *
+ * This is the ONLY human authentication on the platform (LOCAL_STUDIO.md §Publish is
+ * terminal-only). Keys are for CI; humans get a browser and their normal account.
+ */
+import { createServer } from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { getSession, saveSession, freshToken } from "./session.mjs";
+
+export const DISCOVERY_PATH = "/.well-known/unoverse-universe";
+export const CALLBACK_PORT = 4109;
+const CALLBACK_URL = `http://127.0.0.1:${CALLBACK_PORT}/callback`;
+const LOGIN_TIMEOUT_MS = 300_000;
+
+/** What a developer typed → an origin. Mirrors studio's universes.ts. */
+export function normaliseUrl(input) {
+  const trimmed = (input ?? "").trim();
+  if (!trimmed) throw new Error("Enter a universe address");
+  const isLocal = /^(https?:\/\/)?(localhost|127\.0\.0\.1)(:|\/|$)/i.test(trimmed);
+  const withScheme = /^https?:\/\//i.test(trimmed) ? trimmed : `${isLocal ? "http" : "https"}://${trimmed}`;
+  let parsed;
+  try {
+    parsed = new URL(withScheme);
+  } catch {
+    throw new Error(`"${input}" is not a valid address`);
+  }
+  return parsed.origin;
+}
+
+/**
+ * Ask a universe how to log in. Failure is the common case (wrong address, universe
+ * down, a plain website), and each gets a message a developer can act on.
+ */
+export async function discover(origin) {
+  let response;
+  try {
+    response = await fetch(`${origin}${DISCOVERY_PATH}`, { headers: { accept: "application/json" } });
+  } catch {
+    throw new Error(`Could not reach ${origin}. Check the address, and that the universe is running.`);
+  }
+  if (response.status === 404) throw new Error(`Something answered at ${origin}, but it is not a universe.`);
+  if (!response.ok) throw new Error(`${origin} answered with an error (${response.status}).`);
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new Error(`${origin} answered, but not like a universe. If it is one, it may need restarting.`);
+  }
+  if (typeof body?.authEnabled !== "boolean") {
+    throw new Error(`${origin} answered, but not like a universe. If it is one, it may need restarting.`);
+  }
+  return {
+    authEnabled: body.authEnabled,
+    issuer: body.issuer ?? null,
+    clientId: body.clientId ?? null,
+    audience: body.audience ?? null,
+    publishPermission: body.publishPermission ?? "marketplace:publish",
+  };
+}
+
+/** The issuer's own endpoint document. Standard OIDC; both Auth0 and Cognito serve it. */
+export async function oidcEndpoints(issuer) {
+  const base = issuer.replace(/\/+$/, "");
+  let response;
+  try {
+    response = await fetch(`${base}/.well-known/openid-configuration`, { headers: { accept: "application/json" } });
+  } catch {
+    throw new Error(`Could not reach the identity provider at ${issuer}.`);
+  }
+  if (!response.ok) throw new Error(`The identity provider at ${issuer} answered with an error (${response.status}).`);
+  const doc = await response.json();
+  if (!doc?.authorization_endpoint || !doc?.token_endpoint) {
+    throw new Error(`${issuer} does not serve a usable OpenID configuration.`);
+  }
+  return doc;
+}
+
+const b64url = (buf) => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+/** Best effort; the URL is always printed so a developer can click it themselves. */
+function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url.replace(/&/g, "^&")]]
+    : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+  } catch {
+    /* the printed URL is the fallback */
+  }
+}
+
+/** The email inside an id_token, display-only. No verification: nothing trusts it. */
+function emailFrom(idToken) {
+  try {
+    return JSON.parse(Buffer.from(idToken.split(".")[1], "base64url").toString())?.email ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** One loopback round trip: resolves {code} once the browser lands on /callback. */
+function waitForCallback(state) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, `http://127.0.0.1:${CALLBACK_PORT}`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      const finish = (title, body) => {
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end(`<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font-family:system-ui;display:grid;place-items:center;height:100vh;margin:0"><div style="text-align:center"><h1>${title}</h1><p>${body}</p></div>`);
+      };
+      const err = url.searchParams.get("error");
+      if (err) {
+        finish("Sign-in failed", url.searchParams.get("error_description") ?? err);
+        cleanup();
+        rejectPromise(new Error(`The identity provider refused: ${url.searchParams.get("error_description") ?? err}`));
+        return;
+      }
+      if (url.searchParams.get("state") !== state) {
+        finish("Sign-in failed", "State mismatch. Close this tab and run the command again.");
+        cleanup();
+        rejectPromise(new Error("Login state mismatch — the response did not come from this login attempt."));
+        return;
+      }
+      finish("You're signed in", "Return to the terminal.");
+      cleanup();
+      resolvePromise({ code: url.searchParams.get("code") });
+    });
+    const timer = setTimeout(() => {
+      cleanup();
+      rejectPromise(new Error("Login timed out after 5 minutes. Run the command again."));
+    }, LOGIN_TIMEOUT_MS);
+    function cleanup() {
+      clearTimeout(timer);
+      server.close();
+    }
+    server.on("error", (e) => {
+      cleanup();
+      rejectPromise(
+        e.code === "EADDRINUSE"
+          ? new Error(`Port ${CALLBACK_PORT} is in use (another login in progress?). Free it and retry.`)
+          : e,
+      );
+    });
+    server.listen(CALLBACK_PORT, "127.0.0.1");
+  });
+}
+
+/**
+ * Interactive login to one universe. Returns { origin, accessToken, email }.
+ * The session is stored for next time; publish calls this only when no session is live.
+ */
+export async function login(universeInput, { log = console.log } = {}) {
+  const origin = normaliseUrl(universeInput);
+  const config = await discover(origin);
+
+  if (!config.authEnabled) {
+    throw new Error(
+      `${origin} has authentication switched off, so there is no account to sign in with.\n` +
+        `  To publish there, set UNOVERSE_TOKEN to a publish key minted on the universe itself.`,
+    );
+  }
+  if (!config.issuer) throw new Error(`${origin} has no identity provider configured.`);
+  if (!config.clientId) throw new Error(`${origin} has no client id configured for sign-in.`);
+
+  const endpoints = await oidcEndpoints(config.issuer);
+
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  const state = b64url(randomBytes(16));
+
+  // offline_access only where the IdP declares it (Auth0 needs it for a refresh token;
+  // Cognito does not know the scope and refuses requests that name it).
+  const scopes = ["openid", "profile", "email"];
+  if ((endpoints.scopes_supported ?? []).includes("offline_access")) scopes.push("offline_access");
+
+  const authUrl = new URL(endpoints.authorization_endpoint);
+  authUrl.search = new URLSearchParams({
+    response_type: "code",
+    client_id: config.clientId,
+    redirect_uri: CALLBACK_URL,
+    scope: scopes.join(" "),
+    state,
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    ...(config.audience ? { audience: config.audience } : {}),
+  }).toString();
+
+  const pending = waitForCallback(state);
+  log(`\n  Opening your browser to sign in to ${origin}`);
+  log(`  If it does not open: ${authUrl.href}\n`);
+  openBrowser(authUrl.href);
+
+  const { code } = await pending;
+
+  const exchange = await fetch(endpoints.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: config.clientId,
+      code,
+      redirect_uri: CALLBACK_URL,
+      code_verifier: verifier,
+    }),
+  });
+  if (!exchange.ok) {
+    throw new Error(`The identity provider refused the code exchange (${exchange.status}): ${await exchange.text()}`);
+  }
+  const tokens = await exchange.json();
+  const email = tokens.id_token ? emailFrom(tokens.id_token) : null;
+
+  saveSession(origin, {
+    access_token: tokens.access_token,
+    refresh_token: tokens.refresh_token,
+    expires_at: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : undefined,
+    email,
+  });
+
+  log(`  ✓ Signed in${email ? ` as ${email}` : ""}\n`);
+  return { origin, accessToken: tokens.access_token, email };
+}
+
+/**
+ * A token for this universe, however it can be had, in the ruled order:
+ * UNOVERSE_TOKEN (CI) → live session (refreshing) → interactive login (TTY only).
+ */
+export async function tokenFor(origin, { interactive = true, log = console.log } = {}) {
+  if (process.env.UNOVERSE_TOKEN) return process.env.UNOVERSE_TOKEN;
+
+  const config = await discover(origin);
+  if (config.authEnabled && config.issuer && config.clientId) {
+    try {
+      const endpoints = await oidcEndpoints(config.issuer);
+      const live = await freshToken(origin, { tokenEndpoint: endpoints.token_endpoint, clientId: config.clientId });
+      if (live) return live;
+    } catch {
+      /* IdP unreachable: fall through to the interactive path, which explains itself */
+    }
+  } else if (!config.authEnabled) {
+    throw new Error(
+      `${origin} has authentication switched off.\n` +
+        `  To publish there, set UNOVERSE_TOKEN to a publish key minted on the universe itself.`,
+    );
+  }
+
+  if (!interactive || !process.stdin.isTTY) {
+    throw new Error(
+      `No credential for ${origin}. In CI, set UNOVERSE_TOKEN to a publish key.\n` +
+        `  At a terminal, run: unoverse login ${origin}`,
+    );
+  }
+  const { accessToken } = await login(origin, { log });
+  return accessToken;
+}
+
+export { getSession };

package/lib/publish.mjs

@@ -0,0 +1,168 @@
+/**
+ * unoverse publish — ship an asset workspace's items to its universe.
+ *
+ * The terminal face of @unoverse-platform/base items/publish. The order is the safety:
+ * LINT, then COMPARE (a dry-run per item against the universe), then a plan and a
+ * question, then send. Nothing leaves the machine until the rules pass.
+ * (LOCAL_STUDIO.md §Publish is terminal-only; the engine lives in base, this file only
+ * resolves context, formats and asks.)
+ *
+ * Base is consumed as BUILT dist, never source: in this monorepo straight from
+ * packages/base/dist (the in-repo copy wins, same rule as the vendored operator), and in
+ * the published package from the copy vendor-base.mjs froze at pack time.
+ */
+import { existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { findWorkspace, designHome, readConfig, writeConfig } from "./workspace.mjs";
+import { normaliseUrl, tokenFor } from "./login.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const IN_REPO_BASE = resolve(here, "../../base/dist");
+const VENDORED_BASE = resolve(here, "../vendor/base");
+
+async function importBase(subpath) {
+  const root = existsSync(IN_REPO_BASE) ? IN_REPO_BASE : VENDORED_BASE;
+  const file = join(root, subpath);
+  if (!existsSync(file)) {
+    throw new Error(
+      root === IN_REPO_BASE
+        ? `packages/base is not built (${subpath} missing). Run: npm run build -w packages/base`
+        : `This install is missing its vendored base (${subpath}). Reinstall: npm i -g unoverse@latest`,
+    );
+  }
+  return import(pathToFileURL(file).href);
+}
+
+const c = { dim: "\x1b[2m", red: "\x1b[31m", green: "\x1b[32m", yellow: "\x1b[33m", bold: "\x1b[1m", off: "\x1b[0m" };
+const die = (msg) => {
+  console.error(`\n  ${c.red}✗${c.off} ${msg}\n`);
+  process.exit(1);
+};
+
+const ask = async (question) => {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(question);
+  rl.close();
+  return answer.trim();
+};
+
+/**
+ * `unoverse publish [project] [--to <universe>] [--dry-run] [--yes]`
+ * Run from anywhere inside an asset workspace. bin/unoverse.mjs routes here only when
+ * the nearest marker up from cwd is a design home.
+ */
+export async function publish(args) {
+  const flag = (name) => args.includes(`--${name}`);
+  const opt = (name) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+  const positional = args.find((a) => !a.startsWith("--") && a !== opt("to"));
+
+  const ws = findWorkspace();
+  if (ws?.kind !== "assets") die("no design/ folder here or above. Run this inside your workspace.");
+  const designRoot = designHome(ws.root);
+
+  const { collectProject, listProjects } = await importBase("items/collect.js");
+  const { lintForPublish, planPublish, sendPublish } = await importBase("items/publish.js");
+
+  // ── which project ───────────────────────────────────────────────────────────
+  const projects = listProjects(designRoot);
+  if (!projects.length) die(`nothing to publish: ${designRoot} holds no projects`);
+  let project = positional;
+  if (!project) {
+    if (projects.length > 1) {
+      die(`several projects here. Say which:\n\n    unoverse publish <project>\n\n  Found: ${projects.join(", ")}`);
+    }
+    project = projects[0];
+  } else if (!projects.includes(project)) {
+    die(`no project "${project}" in ${designRoot}. Found: ${projects.join(", ") || "none"}`);
+  }
+
+  // ── which universe: --to overrides, unoverse.yaml remembers, first run asks ─
+  const config = await readConfig(ws.root);
+  let universe = opt("to") ?? config.universe;
+  if (!universe) {
+    if (!process.stdin.isTTY) die("no universe. Pass --to https://your-universe.example, or commit it in unoverse.yaml");
+    const typed = await ask(`\n  Where does this workspace publish to? ${c.dim}(e.g. universe.example.com)${c.off} `);
+    if (!typed) die("no universe given");
+    universe = normaliseUrl(typed);
+    await writeConfig(ws.root, { universe });
+    console.log(`  ${c.green}✓${c.off} saved to unoverse.yaml ${c.dim}(commit it: the whole team publishes there)${c.off}`);
+  } else {
+    universe = normaliseUrl(universe);
+  }
+
+  // ── 1. lint. Nothing is sent if this fails ──────────────────────────────────
+  console.log(`\n  ${c.bold}publish ${project}${c.off} ${c.dim}→ ${universe}${c.off}\n`);
+  process.stdout.write(`  ${c.dim}checking…${c.off}`);
+  const { problems, errors } = await lintForPublish(designRoot, project);
+  process.stdout.write("\r                    \r");
+  if (errors.length) {
+    console.error(`  ${c.red}✗ ${errors.length} error(s) in ${project}. Nothing was sent.${c.off}\n`);
+    for (const p of errors.slice(0, 10)) console.error(`    ${p.file}${p.line ? ":" + p.line : ""}  ${p.msg}`);
+    if (errors.length > 10) console.error(`    ${c.dim}…and ${errors.length - 10} more${c.off}`);
+    console.error("");
+    process.exit(1);
+  }
+  const warnings = problems.filter((p) => p.level === "warn").length;
+  console.log(`  ${c.green}✓${c.off} checks passed${warnings ? ` ${c.dim}(${warnings} warning(s))${c.off}` : ""}`);
+
+  // ── 2. the credential, only now that there is something worth sending ───────
+  const items = collectProject(designRoot, project);
+  if (!items.length) die(`nothing to publish in ${project}`);
+  let token;
+  try {
+    token = await tokenFor(universe, { interactive: !flag("yes") });
+  } catch (e) {
+    die(e.message);
+  }
+
+  // ── 3. the plan: what would this publish actually do ────────────────────────
+  let plan;
+  try {
+    plan = await planPublish(items, universe, token);
+  } catch (e) {
+    die(e.message);
+  }
+
+  console.log("");
+  const label = (i) => `${i.kind}/${i.name}`;
+  const pending = (i) => (i.kind === "node" ? ` ${c.yellow}(lands PENDING review)${c.off}` : "");
+  for (const i of plan.create) console.log(`  ${c.green}+${c.off} ${label(i)} ${c.dim}(new)${c.off}${pending(i)}`);
+  for (const i of plan.update) console.log(`  ${c.yellow}~${c.off} ${label(i)} ${c.dim}(changed)${c.off}${pending(i)}`);
+  if (plan.unchanged.length) console.log(`  ${c.dim}= ${plan.unchanged.length} unchanged${c.off}`);
+  for (const r of plan.refused) console.log(`  ${c.red}✗ ${label(r)}${c.off} ${c.dim}${r.why}${c.off}`);
+
+  const toSend = plan.create.length + plan.update.length;
+  if (!toSend) {
+    console.log(`\n  ${c.green}✓${c.off} nothing to do, ${project} is up to date\n`);
+    process.exit(plan.refused.length ? 1 : 0);
+  }
+  if (flag("dry-run")) {
+    console.log(`\n  ${c.dim}dry run: ${toSend} item(s) would be sent${c.off}\n`);
+    process.exit(0);
+  }
+
+  // ── 4. confirm, unless told not to ──────────────────────────────────────────
+  if (!flag("yes")) {
+    const answer = await ask(`\n  ${toSend} item(s) → ${universe}. Publish? [y/N] `);
+    if (!/^y(es)?$/i.test(answer)) {
+      console.log(`  ${c.dim}cancelled${c.off}\n`);
+      process.exit(0);
+    }
+  }
+
+  // ── 5. send ─────────────────────────────────────────────────────────────────
+  const { sent, failed } = await sendPublish(plan, universe, token);
+  console.log("");
+  for (const s of sent) console.log(`  ${c.green}✓${c.off} ${s.mode ?? "sent"} ${c.dim}${s.kind}/${s.name}${c.off}`);
+  for (const f of failed) console.log(`  ${c.red}✗${c.off} ${f.kind}/${f.name}  ${f.why}`);
+  console.log(
+    `\n  ${failed.length ? c.red + "✗" : c.green + "✓"}${c.off} ${sent.length} published` +
+      (failed.length ? `, ${failed.length} failed` : "") + "\n",
+  );
+  process.exit(failed.length ? 1 : 0);
+}

package/lib/session.mjs

@@ -0,0 +1,95 @@
+/**
+ * Per-machine sessions: ~/.unoverse/sessions.json, keyed by universe origin.
+ *
+ * THE REPO SAYS WHERE, THE MACHINE PROVES WHO. unoverse.yaml (committed) names the
+ * universe; this file (0600, home directory, never inside a project) holds the tokens
+ * that prove the developer to it. Same split as .git/config vs ~/.ssh. Nothing under a
+ * project folder ever holds a credential, so nothing can be committed or swept into a
+ * deploy by accident.
+ *
+ * A session is whatever the token endpoint returned: access_token, refresh_token when
+ * the IdP granted one, expiry, and the email shown in prompts. Refresh happens here so
+ * callers only ever ask one question: "a token for this universe, or null".
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const DIR = join(homedir(), ".unoverse");
+const FILE = join(DIR, "sessions.json");
+
+function load() {
+  if (!existsSync(FILE)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(FILE, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {}; // corrupt store: re-login beats a crash
+  }
+}
+
+function save(all) {
+  mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(FILE, JSON.stringify(all, null, 2), { mode: 0o600 });
+  chmodSync(FILE, 0o600); // writeFileSync mode is ignored when the file already exists
+}
+
+export function getSession(origin) {
+  return load()[origin] ?? null;
+}
+
+export function saveSession(origin, session) {
+  const all = load();
+  all[origin] = session;
+  save(all);
+}
+
+export function clearSession(origin) {
+  const all = load();
+  delete all[origin];
+  save(all);
+}
+
+/** Seconds of slack so a token never expires mid-publish. */
+const EXPIRY_SLACK_MS = 60_000;
+
+/**
+ * A live access token for this universe, refreshing if the IdP granted a refresh token,
+ * or null when the developer has to log in again. `tokenEndpoint`/`clientId` come from
+ * the universe's own discovery (login.mjs) — nothing is hardcoded.
+ */
+export async function freshToken(origin, { tokenEndpoint, clientId } = {}) {
+  const session = getSession(origin);
+  if (!session?.access_token) return null;
+  if (session.expires_at && Date.now() < session.expires_at - EXPIRY_SLACK_MS) {
+    return session.access_token;
+  }
+  if (!session.refresh_token || !tokenEndpoint || !clientId) return null;
+
+  let response;
+  try {
+    response = await fetch(tokenEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: clientId,
+        refresh_token: session.refresh_token,
+      }),
+    });
+  } catch {
+    return null; // offline: treat as expired, the caller decides what to say
+  }
+  if (!response.ok) {
+    clearSession(origin); // a refused refresh token is dead; keeping it re-fails forever
+    return null;
+  }
+  const body = await response.json();
+  saveSession(origin, {
+    ...session,
+    access_token: body.access_token,
+    refresh_token: body.refresh_token ?? session.refresh_token,
+    expires_at: body.expires_in ? Date.now() + body.expires_in * 1000 : session.expires_at,
+  });
+  return body.access_token;
+}

package/lib/workspace.mjs

@@ -0,0 +1,72 @@
+/**
+ * The asset workspace: where a developer's design/, prompts/ and nodes/ live.
+ *
+ * Detection mirrors packages/studio/local/{design-home.mjs,catalog.ts} — a workspace is a
+ * folder holding `design/` (or legacy `rx/`, migrated on adoption). A LOCAL copy, same
+ * reason studio keeps one: this package is plain node and cannot import base's TypeScript.
+ * Keep the three in step.
+ *
+ * `unoverse.yaml` at the workspace root is the COMMITTED project config — today one key,
+ * `universe:`, the publish target. It is config, not a secret: the whole team and CI
+ * publish to the same place, which is exactly why it belongs in the repo. Credentials
+ * never live here (they are per machine, in ~/.unoverse — see session.mjs).
+ */
+import { existsSync, renameSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export function hasDesignHome(root) {
+  return existsSync(join(root, "design")) || existsSync(join(root, "rx"));
+}
+
+export function designHome(root) {
+  const design = join(root, "design");
+  const legacy = join(root, "rx");
+  if (!existsSync(design) && existsSync(legacy)) {
+    try {
+      renameSync(legacy, design);
+      console.warn(`  migrated ${legacy} → ${design} (rx/ is now design/)`);
+    } catch (e) {
+      console.warn(`  could not rename ${legacy} → ${design} (${e.message}). Rename it by hand; the platform reads design/ only.`);
+    }
+  }
+  return design;
+}
+
+/**
+ * Walk up from `from` for the nearest marker. The NEAREST one decides what `publish`
+ * means (LOCAL_STUDIO.md §Publish is terminal-only: one verb, the folder decides):
+ * a design home → this is an asset workspace, publish means item rows; a
+ * docker-compose.yml first → this is a universe, publish stays the operator's.
+ * Checked in that order at each level, so a universe folder that also holds a design
+ * tree (the platform monorepo's apps/unoverse) is an asset workspace when you stand in
+ * it, and a universe when you stand at its compose root.
+ */
+export function findWorkspace(from = process.cwd()) {
+  for (let dir = resolve(from); ; ) {
+    if (hasDesignHome(dir)) return { kind: "assets", root: dir };
+    if (existsSync(join(dir, "docker-compose.yml"))) return { kind: "universe", root: dir };
+    const parent = resolve(dir, "..");
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const CONFIG_FILE = "unoverse.yaml";
+
+/** Read unoverse.yaml. Absent file is `{}`, not an error — first publish writes it. */
+export async function readConfig(root) {
+  const path = join(root, CONFIG_FILE);
+  if (!existsSync(path)) return {};
+  const { parse } = await import("yaml");
+  const parsed = parse(readFileSync(path, "utf8"));
+  return parsed && typeof parsed === "object" ? parsed : {};
+}
+
+/** Merge values into unoverse.yaml, preserving whatever else the team keeps there. */
+export async function writeConfig(root, values) {
+  const path = join(root, CONFIG_FILE);
+  const { stringify } = await import("yaml");
+  const next = { ...(await readConfig(root)), ...values };
+  writeFileSync(path, stringify(next));
+  return next;
+}