@rainbow-robotics/muscat-plugin-kit 1.1.5 → 1.3.0

package/README.md

@@ -119,6 +119,54 @@ muscat-pk build                # build dist/ and produce a distributable ZIP (sk
 | `muscat-pk version` | Print the installed CLI version (`-v` / `--version` also work) |
 | `muscat-pk completion [shell]` | Print a shell completion script (`bash` / `zsh` / `fish` / `powershell`; defaults to `$SHELL`) |
 
+### Update policy
+
+`muscat-pk` can be installed globally (npm `-g` or the S3 binary) and/or per
+plugin project (`node_modules`). Two rules keep those from drifting apart:
+
+**The project's local install wins.** When you run `muscat-pk` inside a plugin
+project that has its own install, the CLI hands off to that copy. So the CLI,
+the `vite` preset your `vite.config.ts` imports, and the `preview-host` that
+`dev:ui` launches are always the single version the project pinned — a global
+CLI that is newer or older than the project can't half-apply itself.
+
+**`update` only touches what you're in.**
+
+| Where you run it | What it updates |
+|---|---|
+| Inside a project with a local install | that project's `muscat-plugin-kit` + `plugin-ui` only |
+| Same, with `--global` | the above, plus the global CLI |
+| Anywhere else | the global CLI (and local deps if you're in a project) |
+
+```bash
+muscat-pk update            # this project only
+muscat-pk update --global   # this project + the global CLI
+muscat-pk update dev        # follow the dev channel instead of latest
+muscat-pk version           # which version is actually running here
+```
+
+`dev:ui` also prints a one-line notice when a newer version is published. It is
+skipped by `MUSCAT_PK_NO_UPDATE_CHECK=1` and fails silently offline.
+
+### Offline / air-gapped use
+
+Docker images are only built when they are missing. `docker build` contacts the
+registry to resolve the base image tag on every run — even when every layer is
+cached — so rebuilding an image you already have would break `dev` with no
+network. Once an image exists locally, `muscat-pk` skips the build entirely.
+
+Move images to a machine with no internet:
+
+```bash
+# on a machine with network
+docker save muscat-pk-python-dev muscat-pk-bridge | gzip > muscat-pk-images.tar.gz
+
+# on the offline machine
+gunzip -c muscat-pk-images.tar.gz | docker load
+```
+
+Force a rebuild with `MUSCAT_PK_REBUILD_IMAGE=1`.
+
 ### Shell completion
 
 | OS / shell | Command |
@@ -130,6 +178,57 @@ muscat-pk build                # build dist/ and produce a distributable ZIP (sk
 
 Windows `cmd.exe` has no completion mechanism to hook into — use PowerShell, Git Bash, or WSL.
 
+## Backend port policy
+
+A plugin backend that opens a TCP listener must declare every such port in
+`manifest.json`:
+
+```json
+{ "ports": [28600, 28601] }
+```
+
+| Rule | Enforced by |
+|---|---|
+| Ports must be within `28600-28999` | `muscat-pk build` / `dev` (manifest validation) |
+| Reserved robot/industrial ports are rejected | same — `502`, `2222`, `4840`, `5170-5179`, `8000-8999`, `10000`, `30004`, `34964`, `44818`, `50000-50005`, `50051` |
+| **Every listening port must be declared** | `dev` / `dev:back` runtime monitor — stops the backend on the first undeclared port |
+| No two enabled plugins may claim the same port | the robot, at install time (HTTP 409) |
+
+The runtime monitor is strict on purpose: an undeclared port outside the plugin
+range is invisible to both the monitor and the robot's conflict check, so it
+would only surface as a collision after deployment.
+
+`muscat-pk`'s own dev plumbing (the Socket.IO bridge on `10000`, the Zenoh dev
+peer port) is excluded from the check — it isn't the plugin's traffic.
+
+Declared ports are published to `127.0.0.1` on macOS and Windows so you can
+reach the backend from the host; native Linux uses host networking, where they
+already are.
+
+## Variables (pyfm)
+
+Variables the plugin wants to expose to pyfm programs must be pre-declared in
+`manifest.json` — the Muscat UI lists only declared variables in its variable
+picker:
+
+```json
+{
+  "variables": [
+    { "name": "RBP_grip_force", "type": "number", "init": 0.5, "description": { "ko": "그리퍼 힘 (0~1)", "en": "Gripper force (0–1)" } },
+    { "name": "RBP_target_pose", "type": "array", "init": [0, 0, 0] }
+  ]
+}
+```
+
+| Field | Required | Rule |
+|---|---|---|
+| `name` | yes | must start with `RBP_`, then letters/digits/underscore; unique per plugin |
+| `type` | yes | `"number"` \| `"string"` \| `"array"` |
+| `init` | yes | initial value, must match `type` |
+| `description` | no | string or i18n object (`en` required in object form). Without it the UI shows the variable with no explanation — write one. |
+
+Validated by `muscat-pk build` / `dev` alongside the rest of the manifest.
+
 ## IDE support (Python)
 
 `muscat-pk new` creates a `.venv` at the project root with `requirements.txt` installed. The real backend still runs in a Docker container — this `.venv` exists purely for editor linting (pylint/pyright).

package/cli/README.md

@@ -37,7 +37,17 @@ If a plugin backend opens a TCP server, declare it in `manifest.json`:
 `ports` is optional and accepts only `number[]`; ranges or objects are not
 accepted. External plugin backend ports are reserved for `28600-28999`.
 `muscat-pk dev` and `muscat-pk dev:back` validate the manifest before start and
-stop the backend if it opens an undeclared managed TCP listen port.
+then watch the container: **any listening TCP port that is not declared stops
+the backend**, whatever its number. Since a port outside `28600-28999` cannot be
+declared, it cannot be opened either — otherwise it would slip past both this
+check and the robot's install-time conflict check.
+
+The kit's own dev ports (Socket.IO bridge `10000`, the Zenoh dev peer port) are
+excluded from that check.
+
+Declared ports are published to `127.0.0.1` so the host can reach the backend on
+macOS/Windows; native Linux dev containers use host networking and already have
+them. A declared port that is already busy on the host is skipped with a warning.
 
 Known robot/industrial/internal ports such as `502`, `4840`, `5170-5179`,
 `8000-8999`, `10000`, `2222`, `30004`, `34964`, `44818`, `50000-50005`,
@@ -50,10 +60,10 @@ and `50051` are reserved and must not be used by external plugins.
 | runtime | source | notes |
 |---|---|---|
 | `{ "type": "none" }` | — | UI-only plugin; no backend container |
-| `{ "type": "python", "entry": "main.py" }` | `py/` | Uses `rainbow.rb_sdk.RBPluginCall` for UI/backend messaging |
-| `{ "type": "cpp", "entry": "<executable name>" }` | `cpp/` | Built with CMake in Docker; current template is a run skeleton |
+| `{ "type": "python", "entry": "main.py" }` | `py/` | Uses `rainbow.rb_sdk.RBPluginCall` for UI/backend messaging; `plugin.router` exposes external endpoints (`common/plugin/{id}/{path}`, needs sdk ≥ 0.0.9.dev5 on the robot; the dev bridge only registers routes — external calls need a running `common`) |
+| `{ "type": "cpp", "entry": "<executable name>" }` | `cpp/` | Built with CMake in Docker against the C++ SDK (apt `rainbow-rb-sdk-dev`, `find_package(rb_sdk)`, dynamic link) |
 | `{ "type": "ros2", "rosClient": "rclpy", ... }` | `ros2_ws/` | ROS2 Python node; may use Python SDK alongside ROS2 APIs |
-| `{ "type": "ros2", "rosClient": "rclcpp", ... }` | `ros2_ws/` | ROS2 C++ node built with colcon/CMake |
+| `{ "type": "ros2", "rosClient": "rclcpp", ... }` | `ros2_ws/` | ROS2 C++ node built with colcon/CMake, links the C++ SDK like `cpp` |
 
 All non-`none` runtimes run in Docker during `muscat-pk dev:back`, `muscat-pk
 dev`, and build/export flows so development matches the robot environment.
@@ -229,4 +239,30 @@ offline.
 - `RB_REGISTRY` — registry base URL (default `https://registry.npmjs.org`).
 - `MUSCAT_PK_NO_UPDATE_CHECK=1` — skip the check.
 
+## Local vs global install
+
+If the plugin project has its own `muscat-plugin-kit` in `node_modules`, the CLI
+delegates to it — so the CLI, the `vite` preset, and `preview-host` are always
+the one version the project pinned, no matter which `muscat-pk` you typed.
+
+`muscat-pk update` follows the same rule: run from a project's local install it
+updates only that project; add `--global` to also update the machine-wide CLI.
+`muscat-pk version` prints whichever copy actually ran.
+
+## Docker images
+
+Images are built only when missing, because `docker build` resolves the base
+image tag over the network on every run — even with all layers cached — which
+would break `dev` offline. Pre-seed an air-gapped machine with
+`docker save … | gzip` + `docker load`, or force a rebuild with
+`MUSCAT_PK_REBUILD_IMAGE=1`.
+
+The C++ images (`Dockerfile.cpp`, `Dockerfile.dev`) install `rainbow-rb-sdk-dev`
+from `https://rainbowrobotics.github.io/rb-sdk` (suite `dev`), pinned by the
+`RB_SDK_VERSION` build arg. Set `MUSCAT_PK_RB_SDK_VERSION=<version>` (with
+`MUSCAT_PK_REBUILD_IMAGE=1`) to match a robot running a different SDK version.
+
+On Linux the dev containers run as the invoking user (`--user`), so build output
+under `dist/` and `cpp/build-*` is not left root-owned.
+
 Full spec: [`docs/plugin-system/CREATE-CLI.md`](../../docs/plugin-system/CREATE-CLI.md).

package/cli/bin/muscat-pk.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 // muscat-pk — Muscat plugin developer CLI.
 // Subcommands: new, build, dev, dev:ui, dev:back, storybook, mcp, update, uninstall, sdk, version.
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { color, kitVersion, log, resolveLocalCliBin } from "../src/util.mjs";
@@ -24,15 +25,39 @@ import { runCompletion } from "../src/completion.mjs";
 // 실행 중인 게 글로벌/바이너리인데 cwd 상위에 로컬 설치가 있으면 그쪽으로 넘긴다.
 // vite preset / preview-host / manifest 검증이 항상 프로젝트가 고정한 버전과
 // 맞아야 해서다 (버전이 안 맞으면 "module not found" 류 에러로 터진다).
+function readVersion(binPath) {
+  try {
+    return JSON.parse(readFileSync(resolve(binPath, "../../../package.json"), "utf8")).version;
+  } catch {
+    return "";
+  }
+}
+
+const isBinaryMode = typeof Bun !== "undefined";
+
 (function delegateToLocalInstall() {
   try {
     const localBin = resolveLocalCliBin();
     if (!localBin) return;
-    if (realpathSync(localBin) === realpathSync(fileURLToPath(import.meta.url))) return;
-    const r = spawnSync(process.execPath, [localBin, ...process.argv.slice(2)], { stdio: "inherit" });
+    // 바이너리는 node_modules 안의 mjs일 수 없으니 자기 자신 비교 생략.
+    // (import.meta.url이 /$bunfs/ 가상 경로라 realpath가 throw하기도 한다.)
+    if (!isBinaryMode && realpathSync(localBin) === realpathSync(fileURLToPath(import.meta.url))) return;
+    // Say so — otherwise an outdated local copy silently answers instead, and
+    // its missing/renamed subcommands look like the CLI is broken.
+    const localVersion = readVersion(localBin);
+    console.error(
+      color.dim(`[muscat-pk] using this project's local install${localVersion ? ` (v${localVersion})` : ""}: ${localBin}`),
+    );
+    // Bun 바이너리의 execPath는 스크립트 인자를 실행하지 않으니 PATH의 node로 넘긴다.
+    const runtime = isBinaryMode ? "node" : process.execPath;
+    const r = spawnSync(runtime, [localBin, ...process.argv.slice(2)], { stdio: "inherit" });
+    if (r.error) {
+      log.warn(`Failed to run local install via ${runtime} (${r.error.code}); continuing with this binary.`);
+      return;
+    }
     process.exit(r.status ?? 0);
   } catch {
-    // Bun 단일 바이너리 등 realpath가 안 통하는 환경 — 그냥 지금 프로세스로 계속.
+    // realpath 실패 등 — 그냥 지금 프로세스로 계속.
   }
 })();
 
@@ -55,7 +80,7 @@ function formatHelp() {
     commandRow("dev:ui", `Preview the plugin in a mini-Muscat ${color.dim("(preview-host)")}`),
     commandRow("dev:back", `Run the plugin back end ${color.dim("(python: watchfiles reload / ros2: Docker)")}`),
     commandRow("storybook", `Browse the bundled rb-components Storybook ${color.dim(`(${option("--port")} <n>, ${option("--rebuild")})`)}`),
-    commandRow("mcp", `Start an MCP server ${color.dim("(stdio)")} exposing rb-components/rb SDK docs to AI agents`),
+    commandRow("mcp", `Start an MCP server ${color.dim("(stdio)")} exposing rb-components/rb SDK docs to AI agents ${color.dim(`(${option("--install")} codex: register in ~/.codex/config.toml)`)}`),
     commandRow("update", `Update ${color.magenta("@rainbow-robotics/muscat-plugin-kit")} and ${color.magenta("@rainbow-robotics/plugin-ui")} ${color.dim(`(local-only if run from a project's local install; ${option("--global")} also updates the global CLI)`)}`),
     commandRow("uninstall", `Remove the installed ${color.cyan("muscat-pk")} CLI ${color.dim("(npm global or S3 binary)")}`),
     commandRow("sdk <list|update [version]>", "Manage the python rainbow-rb-sdk version"),
@@ -84,7 +109,9 @@ async function main() {
       case "storybook":
         return await runStorybook(args);
       case "mcp": {
-        const { runMcp } = await import("../src/mcp.mjs");
+        const { runMcp, installMcp } = await import("../src/mcp.mjs");
+        if (args[0] === "--install" || args[0] === "install")
+          return installMcp(args[1]);
         return await runMcp(args);
       }
       case "update":

package/cli/docker/Dockerfile.cpp

@@ -10,12 +10,17 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       cmake \
     && rm -rf /var/lib/apt/lists/*
 
-# TODO(cpp-sdk): install the rainbow cpp SDK (dev package) here, pinned to the
-# robot's version, so plugins build/link against the same SDK as production.
-# Plan: apt package + dynamic link (the robot provides the .so at runtime;
-# we do NOT bundle it into the plugin binary). e.g.:
-#   RUN apt-get update && apt-get install -y rainbow-cpp-sdk-dev=<robot-version> \
-#       && rm -rf /var/lib/apt/lists/*
+# Rainbow Robotics C++ SDK (rainbow-rb-sdk-dev): headers + CMake config for
+# find_package(rb_sdk). Pinned to the robot's SDK version — the binary links
+# librb_sdk.so.<ver> by SONAME and the robot provides that exact .so at runtime.
+# Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
+ARG RB_SDK_VERSION=0.1.2~dev1
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
+    && install -d /etc/apt/keyrings \
+    && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
+    && echo 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk dev main' > /etc/apt/sources.list.d/rb-sdk.list \
+    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /plugin
 

package/cli/docker/Dockerfile.dev

@@ -9,6 +9,18 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       python3-colcon-common-extensions \
     && rm -rf /var/lib/apt/lists/*
 
+# Rainbow Robotics C++ SDK (rainbow-rb-sdk-dev): headers + CMake config for
+# find_package(rb_sdk). Pinned to the robot's SDK version — the binary links
+# librb_sdk.so.<ver> by SONAME and the robot provides that exact .so at runtime.
+# Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
+ARG RB_SDK_VERSION=0.1.2~dev1
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
+    && install -d /etc/apt/keyrings \
+    && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
+    && echo 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk dev main' > /etc/apt/sources.list.d/rb-sdk.list \
+    && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
+    && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /plugin
 
 CMD ["bash"]

package/cli/src/build.mjs

@@ -65,11 +65,11 @@ function runViteBuild(pluginRoot, { mode = "production" } = {}) {
   if (r.status !== 0) throw new Error("vite build failed");
 }
 
-function isMainBranch() {
-  const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
-  const branch = r.stdout?.trim();
-  return branch === "main" || branch === "master";
-}
+// function isMainBranch() {
+//   const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+//   const branch = r.stdout?.trim();
+//   return branch === "main" || branch === "master";
+// }
 
 // For ros2 plugins, compile the colcon workspace inside the Jazzy + Python 3.12 container.
 // rclpy: arch-agnostic (pure Python) → dist/ros2_ws/install/ (built once)
@@ -169,7 +169,7 @@ function isPrerelease(version) {
 // stableOnly=true → skips pre-release (dev/a/b/rc) versions.
 async function latestPypiVersion(pkg, { stableOnly = false } = {}) {
   const res = await fetch(`https://pypi.org/pypi/${pkg}/json`, {
-    signal: AbortSignal.timeout(5000),
+    signal: new AbortController().signal.timeout(5000),
   });
   if (!res.ok) throw new Error(`pypi ${pkg}: ${res.status}`);
   const data = await res.json();

package/cli/src/cpp.mjs

@@ -22,9 +22,11 @@ export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null } = {
   const dockerfile = await resolveDockerfile("Dockerfile.cpp");
   log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
   const platformFlags = platform ? ["--platform", platform] : [];
+  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const buildArgs = sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : [];
   const r = spawnSync(
     "docker",
-    ["build", ...platformFlags, "-t", image, "-f", dockerfile, dirname(dockerfile)],
+    ["build", ...platformFlags, ...buildArgs, "-t", image, "-f", dockerfile, dirname(dockerfile)],
     { stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error("docker build failed.");

package/cli/src/dev.mjs

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack, stopDevBackContainers } from "./devBack.mjs";
 import { startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
-import { assertManifestPorts } from "./manifest.mjs";
+import { assertManifestPorts, assertManifestVariables } from "./manifest.mjs";
 import { formatPortRanges } from "./ports.mjs";
 import {
   ensureDocker,
@@ -111,6 +111,7 @@ async function maybeStartHostAgent(root, { robotIp, robotToken }) {
 
 export async function runDev(args = []) {
   const root = findPluginRoot();
+  assertManifestVariables(root);
   const portRanges = assertManifestPorts(root);
   if (portRanges.length > 0) {
     log.step(`plugin backend ports declared: ${formatPortRanges(portRanges)}`);

package/cli/src/devBack.mjs

@@ -10,9 +10,9 @@
 import { spawn, spawnSync } from "node:child_process";
 import { existsSync, watch } from "node:fs";
 import { resolve } from "node:path";
-import { ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection } from "./util.mjs";
+import { ensureDocker, ensureIdeVenv, findPluginRoot, log, promptRobotConnection, realtimeFlags } from "./util.mjs";
 import { ensureRemoteZenohEnv, usesHostNetwork } from "./zenohDev.mjs";
-import { assertManifestPorts, manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
+import { assertManifestPorts, assertManifestVariables, manifestRuntime, readManifest, validateManifest } from "./manifest.mjs";
 import {
   formatPortRanges,
   portEnvFlags,
@@ -147,7 +147,7 @@ async function runPython(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting Python dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...netFlags, ...standaloneZenohPortFlags, ...pluginPortFlags,
+    ["run", "-d", "--name", container, ...netFlags, ...standaloneZenohPortFlags, ...pluginPortFlags, ...realtimeFlags(),
       // host.docker.internal is automatic on Docker Desktop (macOS/Windows);
       // this makes it resolve on Linux too, for the no-bridge gateway fallback above.
       ...hostGatewayFlags,
@@ -445,11 +445,11 @@ async function runRos2(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting ROS2 dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), ...realtimeFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   // one-time deps + symlink build (edits to .py reflect without rebuilding)
   log.step("pip install + colcon build --symlink-install (once)…");
@@ -526,11 +526,11 @@ async function runCpp(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting C++ dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), ...realtimeFlags(), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
-  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log });
+  const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   const build = () => {
     log.step("cmake build…");
@@ -585,6 +585,7 @@ function warnManifest(root) {
 
 export async function runDevBack(args = []) {
   const root = findPluginRoot();
+  assertManifestVariables(root);
   warnManifest(root);
   const portRanges = assertManifestPorts(root);
   if (portRanges.length > 0 && process.env.MUSCAT_PK_PORTS_PRECHECKED !== "1")

package/cli/src/manifest.mjs

@@ -15,6 +15,9 @@ const RUNTIME_TYPES = ["none", "python", "cpp", "ros2"];
 const ROS_CLIENTS = ["rclpy", "rclcpp"];
 const I18N_LANGS = ["ko", "en", "ja", "zh", "vi", "th", "es"];
 const TARGET_CATEGORIES = ["manipulate", "amr", "rby1", "vision"];
+const VARIABLE_TYPES = ["number", "string", "boolean", "array"];
+const VARIABLE_NAME_PREFIX = "RBP_";
+const VARIABLE_NAME_RE = /^RBP_[A-Za-z0-9_]+$/;
 
 function validateI18nLabel(value, field, errors) {
   if (value === undefined || value === null) {
@@ -110,6 +113,46 @@ function validateCommandInfo(info, prefix, errors) {
     errors.push(`${prefix}.commandInfo.childrenCommand must be a string`);
 }
 
+// variables: pyfm에 노출할 변수 선언. 없으면 UI가 사용 가능한 변수를 보여줄 수 없다.
+function validateVariables(variables, errors) {
+  if (variables === undefined || variables === null) return;
+  if (!Array.isArray(variables)) {
+    errors.push(`"variables" must be an array`);
+    return;
+  }
+  const names = variables.map((v) => v?.name).filter(Boolean);
+  const duplicates = names.filter((n, i) => names.indexOf(n) !== i);
+  if (duplicates.length > 0)
+    errors.push(`variables: "name" must be unique (duplicates: ${[...new Set(duplicates)].map((n) => `"${n}"`).join(", ")})`);
+
+  variables.forEach((v, i) => {
+    if (typeof v !== "object" || v === null || Array.isArray(v)) {
+      errors.push(`variables[${i}] must be an object ({ name, type, init, description? })`);
+      return;
+    }
+    if (typeof v.name !== "string" || v.name.length === 0)
+      errors.push(`variables[${i}].name is required`);
+    else if (!v.name.startsWith(VARIABLE_NAME_PREFIX))
+      errors.push(`variables[${i}].name: "${v.name}" must start with "${VARIABLE_NAME_PREFIX}" (e.g. "${VARIABLE_NAME_PREFIX}${v.name}")`);
+    else if (!VARIABLE_NAME_RE.test(v.name))
+      errors.push(`variables[${i}].name: "${v.name}" is not a valid identifier (after "${VARIABLE_NAME_PREFIX}": letters, digits, underscore only, at least one character)`);
+    if (!VARIABLE_TYPES.includes(v.type))
+      errors.push(`variables[${i}].type must be one of ${VARIABLE_TYPES.map((t) => `"${t}"`).join(" | ")}`);
+    if (v.init === undefined)
+      errors.push(`variables[${i}].init is required (initial value)`);
+    else if (v.type === "number" && typeof v.init !== "number")
+      errors.push(`variables[${i}].init must be a number when type is "number"`);
+    else if (v.type === "string" && typeof v.init !== "string")
+      errors.push(`variables[${i}].init must be a string when type is "string"`);
+    else if (v.type === "boolean" && typeof v.init !== "boolean")
+      errors.push(`variables[${i}].init must be a boolean when type is "boolean"`);
+    else if (v.type === "array" && !Array.isArray(v.init))
+      errors.push(`variables[${i}].init must be an array when type is "array"`);
+    if (v.description !== undefined && v.description !== null)
+      validateI18nLabel(v.description, `variables[${i}].description`, errors);
+  });
+}
+
 function validateContributes(contributes, errors) {
   if (!Array.isArray(contributes) || contributes.length === 0) {
     errors.push("contributes is required and must be a non-empty array");
@@ -183,6 +226,7 @@ export function validateManifest(manifest) {
   validatePorts(manifest.ports, errors);
   validateRuntime(manifest.runtime, errors);
   validateContributes(manifest.contributes, errors);
+  validateVariables(manifest.variables, errors);
 
   return errors;
 }
@@ -202,6 +246,18 @@ export function assertManifest(root) {
   return manifest;
 }
 
+export function assertManifestVariables(root) {
+  const manifest = readManifest(root);
+  if (manifest === null)
+    throw new Error("manifest.json parse failed — check JSON syntax");
+  if (Object.keys(manifest).length === 0)
+    return;
+  const errors = [];
+  validateVariables(manifest.variables, errors);
+  if (errors.length > 0)
+    throw new Error(`manifest.json variable errors:\n${errors.map((e) => `  • ${e}`).join("\n")}`);
+}
+
 export function assertManifestPorts(root) {
   const manifest = readManifest(root);
   if (manifest === null)