@unoverse-platform/studio 0.1.52 → 0.1.54

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";
 
@@ -163,6 +164,54 @@ const projectRoot = findProjectRootFromCwd();
 process.env.UNOVERSE_HOME = projectRoot;
 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

@@ -71,6 +71,16 @@ 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;
 }
 
@@ -94,6 +104,17 @@ export function createFirstProject(home, name) {
     cpSync(samples, join(home, "nodes/samples"), { recursive: true });
   }
 
+  // A worked example agent skill and prompt block, same reason and same rule as the
+  // sample nodes: prompts/ must never be two empty folders, and the samples are the
+  // developer's to edit or delete — copied only when absent, never restored.
+  const samplePrompts = join(dirname(fileURLToPath(import.meta.url)), "sample-prompts");
+  if (existsSync(join(samplePrompts, "skills")) && !existsSync(join(home, "prompts/skills/sample-complaint-handling"))) {
+    cpSync(join(samplePrompts, "skills"), join(home, "prompts/skills"), { recursive: true });
+  }
+  if (existsSync(join(samplePrompts, "blocks")) && !existsSync(join(home, "prompts/blocks/formatting/sample-concise-answers.md"))) {
+    cpSync(join(samplePrompts, "blocks"), join(home, "prompts/blocks"), { recursive: true });
+  }
+
   // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "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>
                 )}