@unoverse-platform/studio 0.1.53 → 0.1.55

package/bin/studio.mjs

@@ -21,6 +21,7 @@ import { dirname, resolve, join, basename } from "path";
 import { fileURLToPath } from "url";
 import { existsSync, readdirSync } from "fs";
 import { createInterface } from "readline/promises";
+import { execSync } from "child_process";
 import { designHome, hasDesignHome } from "../local/design-home.mjs";
 import { createFirstProject, checkProjectName } from "../local/scaffold.mjs";
 
@@ -161,8 +162,63 @@ await scaffoldIfEmpty();
  */
 const projectRoot = findProjectRootFromCwd();
 process.env.UNOVERSE_HOME = projectRoot;
+// Samples this workspace has never seen arrive on launch (new ones ship with Studio
+// releases); anything it ever had — edited or deleted — is never touched. scaffold.mjs
+// topUpSamples explains the record that makes that distinction safe.
+{
+  const { topUpSamples } = await import("../local/scaffold.mjs");
+  try { topUpSamples(projectRoot); } catch { /* a read-only folder must not block launch */ }
+}
 console.log(`\n  Studio reading: ${designHome(projectRoot)}\n`);
 
+/**
+ * LAUNCHING STUDIO IS THE DECISION; A STALE STUDIO YIELDS THE PORT.
+ *
+ * Studio is always 4108 with strictPort, so the address in your browser's history is
+ * always the right one. The price of one fixed port used to be a raw vite "Port 4108
+ * is already in use" whenever a previous Studio was still running — the tab from the
+ * last session, forgotten, holding the port for a project you have moved on from.
+ * Typing `unoverse studio` again IS the answer to "which one do you want": the old
+ * instance is stopped and this one takes the port.
+ *
+ * ONLY a recognisable Studio is stopped. Anything else on 4108 is somebody's own
+ * process, and killing it on sight would be worse than the error, so that case names
+ * the process and stops.
+ */
+function freePortOfStaleStudio(port) {
+  let pids = [];
+  try {
+    pids = execSync(`lsof -nP -ti tcp:${port} -s tcp:LISTEN`, { stdio: ["ignore", "pipe", "ignore"] })
+      .toString().trim().split("\n").filter(Boolean);
+  } catch {
+    return; // nothing listening, or no lsof: let vite find out
+  }
+  for (const pid of pids) {
+    if (pid === String(process.pid)) continue;
+    let command = "";
+    try {
+      command = execSync(`ps -p ${pid} -o command=`, { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    } catch { continue; } // already gone
+    if (/unoverse-studio|@unoverse-platform\/studio|packages\/studio/.test(command)) {
+      console.log(`  A previous Studio was still holding :${port}. Stopping it and taking over.`);
+      try { process.kill(Number(pid), "SIGTERM"); } catch { /* already gone */ }
+      // SIGTERM first so it closes cleanly; escalate only if it lingers.
+      const deadline = Date.now() + 3000;
+      for (;;) {
+        try { process.kill(Number(pid), 0); } catch { break; } // no longer exists
+        if (Date.now() > deadline) { try { process.kill(Number(pid), "SIGKILL"); } catch { /* gone */ } break; }
+        execSync("sleep 0.2");
+      }
+    } else {
+      console.error(`\n  Port ${port} is held by something that is not Studio:\n    ${command}\n`);
+      console.error(`  Stop it (kill ${pid}) or find out what it is (lsof -nP -i :${port}), then run unoverse studio again.\n`);
+      process.exit(1);
+    }
+  }
+}
+
+freePortOfStaleStudio(4108);
+
 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.

package/local/sample-prompts/blocks/formatting/sample-concise-answers.md

@@ -0,0 +1,22 @@
+---
+name: Concise Answers
+description: Keeps replies short, direct, and free of filler — the answer first, detail only on request
+tags: [formatting, tone]
+---
+
+<!-- A WORKED EXAMPLE prompt block, shipped with Studio so prompts/blocks/ is never an
+     empty folder. Edit it, copy it, or delete it — it is yours. A block is a reusable
+     prompt fragment workflows compose into an agent's system prompt: smaller than a
+     skill, no routing of its own, and it must stand alone (no references to other
+     blocks). The folder above it is its category. -->
+
+Answer the question first, in one or two sentences, before any background.
+
+Keep every reply as short as it can be while still being complete. Cut greetings,
+restatements of the question, and closing filler ("I hope this helps").
+
+Use plain words over formal ones. Prefer an example over an explanation when one
+example makes the point.
+
+If the full answer would be long, give the short version and offer the detail:
+"Want the full breakdown?"

package/local/sample-prompts/skills/sample-complaint-handling/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sample-complaint-handling
+title: Complaint Handling
+description: How the assistant responds when a customer is unhappy, from first reply to escalation
+whenToUse: Handle an unhappy customer — a complaint, frustration with the product or service, a request for a refund, or a demand to speak to a person. Not for neutral questions or how-to requests.
+version: 1.0.0
+category: ai
+triggers:
+  - complaint
+  - refund
+  - unhappy
+  - speak to a human
+  - escalate
+---
+
+# Complaint Handling
+
+<!-- A WORKED EXAMPLE, shipped with Studio so prompts/skills/ is never an empty folder.
+     Edit it, copy it, or delete it — it is yours. An agent skill is prose the
+     platform's AI agents discover at runtime and follow: the frontmatter above is the
+     routing (whenToUse is ranked against what the user actually says), the body below
+     is the behavior. Format + rules: https://docs.unoverse.ai/nodes/node-discoverability.md -->
+
+## When to Use This Skill
+
+The customer is expressing dissatisfaction: something broke, something was late, they
+were charged wrongly, or they are simply frustrated. The goal of every reply is that
+the customer feels heard first and helped second.
+
+## Approach
+
+1. **Acknowledge before anything else.** One sentence that names their problem in
+   their words. Never open with policy.
+2. **Ask for the one detail you need**, if any, and only one at a time.
+3. **Offer the concrete next step you can actually do.** Do not promise outcomes you
+   cannot see through.
+4. **Escalate when asked, and say so plainly.** If the customer asks for a person
+   twice, or mentions legal action, stop resolving and hand off: "I'm passing this to
+   our team; you'll hear from a person."
+
+## Do / Don't
+
+- Do keep replies to three sentences or fewer while the customer is upset.
+- Do use their name if you have it.
+- Don't defend the company or explain why the problem happened, unless they ask.
+- Don't offer discounts or refunds beyond what the workflow's tools allow.
+
+## Examples
+
+Customer: "This is the second time my order arrived broken. Ridiculous."
+Reply: "Twice in a row is genuinely not okay — I'm sorry. I can send a replacement
+today or refund the order in full: which would you prefer?"

package/local/sample-styles/README.md

@@ -0,0 +1,23 @@
+# Your project's styles
+
+This folder restyles the whole design system for your brand — without editing a
+single component. Three rules:
+
+1. **Token NAMES are the contract, VALUES are yours.** Components reference names
+   like `text.primary` and `action.primary`; you change what those names mean.
+2. **Name a token to override it; omit it to inherit.** The cascade is per token,
+   never per file. Never copy a whole file to change one line — the untouched lines
+   would stop tracking platform improvements.
+3. **Ingredients in `base/`, meaning in `themes/`.** `base/color.yaml` names your
+   brand's raw colors (`color.brand.ink`); a theme file assigns them to roles
+   (`text.primary: {color.brand.ink}`).
+
+Start here:
+
+- `base/color.yaml` — name your brand ingredients (a worked example is inside).
+- Want your own theme? Copy the foundation's theme file whole — the ONE place
+  copying is correct, because a theme must assign every role:
+  https://github.com/unoverse-platform/marketplace/tree/main/definitions/styles/themes
+  → save as `themes/light.yaml` here, then point roles at your `color.brand.*`.
+
+Full guide: https://docs.unoverse.ai/design/styles-and-tokens.md

package/local/sample-styles/base/color.yaml

@@ -0,0 +1,18 @@
+# BRAND INGREDIENTS — raw colors named for what they ARE (ink, paper, a signature
+# hue), never for where they are used ("button-blue" is a decision, not an ingredient;
+# a theme file makes decisions). These are inert until a theme assigns them to roles,
+# so this file is safe to grow before you have a theme at all.
+#
+# Delete the examples and name your own. Guide: see README.md in this folder.
+color:
+  $type: color
+  brand:
+    ink:
+      $value: "#1a1a2e"
+      $description: "Near-black with a hint of the brand hue — body text and headings"
+    paper:
+      $value: "#fbfaf8"
+      $description: "Warm off-white — page and card backgrounds"
+    signature:
+      $value: "#4f46e5"
+      $description: "The brand's signature hue — actions and accents"

package/local/scaffold.mjs

@@ -13,7 +13,7 @@
  *
  * See docs/architecture/LOCAL_STUDIO.md.
  */
-import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, cpSync, readdirSync, readFileSync } from "node:fs";
 import { designHome } from "./design-home.mjs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -71,9 +71,73 @@ export function createProject(home, name) {
 
   for (const d of ["components/welcome", "templates", "styles"]) mkdirSync(join(root, d), { recursive: true });
   writeFileSync(join(root, "components/welcome/welcome.yaml"), WELCOME);
+
+  // Worked example styles (sample-styles: brand ingredients + the override rules), so
+  // styles/ is never an empty folder with no hint of the token cascade. Per PROJECT,
+  // because every project is a publishable org with its own pack. Copied only when the
+  // folder is empty: these are the developer's files, and a later run must never put
+  // back what they threw away.
+  const sampleStyles = join(dirname(fileURLToPath(import.meta.url)), "sample-styles");
+  if (existsSync(sampleStyles) && readdirSync(join(root, "styles")).length === 0) {
+    cpSync(sampleStyles, join(root, "styles"), { recursive: true });
+  }
   return root;
 }
 
+/**
+ * The worked example content (sample nodes, a sample agent skill, a sample prompt
+ * block), keyed by the workspace path each lands at. `dir` is relative to this file.
+ *
+ * A NEW ENTRY HERE REACHES EXISTING WORKSPACES on their next Studio launch, because
+ * topUpSamples runs at every launch, not only at scaffold. The record below is what
+ * makes that safe.
+ */
+const SAMPLES = [
+  { id: "nodes/samples", dir: "sample-nodes/samples", to: "nodes/samples" },
+  { id: "prompts/skills/sample-complaint-handling", dir: "sample-prompts/skills/sample-complaint-handling", to: "prompts/skills/sample-complaint-handling" },
+  { id: "prompts/blocks/sample-concise-answers", dir: "sample-prompts/blocks/formatting/sample-concise-answers.md", to: "prompts/blocks/formatting/sample-concise-answers.md" },
+];
+
+/**
+ * Install every sample this workspace has NEVER SEEN, and only those.
+ *
+ * "Absent from disk" is ambiguous — it means either "deleted on purpose" or "shipped
+ * after this workspace was made" — so presence is not the test. The test is the
+ * RECORD (.unoverse/samples.json): a sample id listed there was installed here once,
+ * and whatever the developer did to it since (edit, rename, delete) is theirs and
+ * permanent. A sample id NOT listed is genuinely new to this workspace and arrives.
+ * That is what lets `unoverse studio` top up new samples on every launch without ever
+ * resurrecting deleted work or overwriting changed files.
+ */
+export function topUpSamples(home) {
+  const record = join(home, ".unoverse", "samples.json");
+  let seen = [];
+  try {
+    seen = JSON.parse(readFileSync(record, "utf8")).installed ?? [];
+  } catch {
+    // No record: a workspace from before records existed. Treat every sample already
+    // on disk as seen (it was installed by an old scaffold), so nothing is re-copied.
+    seen = SAMPLES.filter((s) => existsSync(join(home, s.to))).map((s) => s.id);
+  }
+  const here = dirname(fileURLToPath(import.meta.url));
+  let changed = false;
+  for (const s of SAMPLES) {
+    if (seen.includes(s.id)) continue;
+    const src = join(here, s.dir);
+    if (!existsSync(src)) continue;
+    if (!existsSync(join(home, s.to))) {
+      mkdirSync(dirname(join(home, s.to)), { recursive: true });
+      cpSync(src, join(home, s.to), { recursive: true });
+    }
+    seen.push(s.id);
+    changed = true;
+  }
+  if (changed || !existsSync(record)) {
+    mkdirSync(dirname(record), { recursive: true });
+    writeFileSync(record, JSON.stringify({ installed: seen }, null, 2) + "\n");
+  }
+}
+
 /**
  * The FIRST project, plus the folders that live beside the design tree rather than inside it.
  *
@@ -84,36 +148,20 @@ 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 });
 
-  // Two worked example nodes (sample-nodes/samples: a PromiseNode and a CallbackNode,
-  // heavily commented, linking docs.unoverse.ai/nodes), so `nodes/` is never an empty
-  // folder with no hint of what goes in it. Copied only when absent: these are the
-  // developer's files to edit or delete, and a later scaffold run must never put back
-  // what they threw away or overwrite what they changed.
-  const samples = join(dirname(fileURLToPath(import.meta.url)), "sample-nodes/samples");
-  if (existsSync(samples) && !existsSync(join(home, "nodes/samples"))) {
-    cpSync(samples, join(home, "nodes/samples"), { recursive: true });
-  }
+  topUpSamples(home);
 
-  // The Claude Code authoring skills, so "open the folder and describe what you want"
-  // works in every Studio project from its first minute. Vendored into the published
-  // app (vendor/skills, written by prepack from the monorepo's .claude/skills, the one
-  // authoring home, mirrored publicly to github.com/unoverse-platform/skills); read
-  // from that home when running as source. `unoverse update` refreshes installed
-  // copies from the public mirror.
+  // SCAFFOLD WRITES NO `.claude/skills` (2026-08-21). It used to copy the Claude Code
+  // authoring skills out of `vendor/skills` and into `<home>/.claude/skills`, which meant
+  // every remote developer who launched Studio got the platform repo's own `.claude`
+  // folder reproduced on their disk, pinned to whatever Studio version they happened to
+  // install and sitting in a workspace they might commit.
   //
-  // ALL of them. One Studio project is where a person designs a brand AND writes the node
-  // behind it, so they need the whole set: naming one skill here shipped the authoring
-  // playbooks and silently withheld the rest.
-  const app = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-  const skillsDir = [join(app, "vendor/skills"), resolve(app, "../../.claude/skills")].find((d) => existsSync(d));
-  if (skillsDir) {
-    const names = readdirSync(skillsDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory() && existsSync(join(skillsDir, e.name, "SKILL.md")))
-      .map((e) => e.name);
-    if (names.length) mkdirSync(join(home, ".claude/skills"), { recursive: true });
-    for (const name of names) {
-      cpSync(join(skillsDir, name), join(home, ".claude/skills", name), { recursive: true });
-    }
-  }
+  // The skills are PER DEVELOPER, not per project (the same reason prompts/ and nodes/ are
+  // made once here and never by `createProject`). They now install to `~/.claude/skills`
+  // from the public mirror, on `unoverse update` — see packages/cli/lib/skills.mjs.
+  //
+  // `vendor/skills` STAYS, and is not a distribution channel: it is what Studio's builder
+  // MCP reads to teach a connected agent the authoring rules (local/mcp.ts SKILL_DIRS).
+  // Nothing about that copy reaches the developer's filesystem.
   return root;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {

package/src/NodesView.tsx

@@ -383,7 +383,12 @@ export function NodesView() {
               </div>
               <div className="ml-auto flex shrink-0 items-center gap-2">
                 {current.testData && (
-                  <button onClick={loadSample} className="rounded border border-gray-700 px-3 py-1.5 text-sm font-medium text-gray-300 hover:bg-white/5">
+                  <button
+                    onClick={loadSample}
+                    disabled={!current?.testData}
+                    title={current?.testData ? "Fill the form from the node's test fixture (test.yaml)" : "This node declares no test fixture"}
+                    className="rounded border border-gray-300 bg-white px-3 py-1.5 text-sm font-medium text-gray-700 shadow-sm hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-40"
+                  >
                     Load sample
                   </button>
                 )}