@rainbow-robotics/muscat-plugin-kit 1.1.4 → 1.2.1

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`,
@@ -229,4 +239,25 @@ 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`.
+
+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,11 @@
 #!/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 { color, kitVersion, log } from "../src/util.mjs";
+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";
 import { runNew } from "../src/new.mjs";
 import { runBuild } from "../src/build.mjs";
 import { runDevUi } from "../src/devUi.mjs";
@@ -18,6 +22,45 @@ import { runCompletion } from "../src/completion.mjs";
 // on every invocation otherwise (see ros2.mjs/python.mjs/cpp.mjs for the same
 // pattern in build.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;
+    // 바이너리는 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 {
+    // realpath 실패 등 — 그냥 지금 프로세스로 계속.
+  }
+})();
+
 const [, , cmd, ...args] = process.argv;
 
 const commandRow = (command, description) => `  ${color.cyan(command.padEnd(30))}${description}`;
@@ -37,8 +80,8 @@ 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("update", `Update ${color.magenta("@rainbow-robotics/muscat-plugin-kit")} and ${color.magenta("@rainbow-robotics/plugin-ui")}`),
+    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"),
     commandRow("version", `Print the installed ${color.cyan("muscat-pk")} version`),
@@ -66,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/src/bridge.mjs

@@ -7,7 +7,7 @@ import { spawnSync } from "node:child_process";
 import { createServer, connect } from "node:net";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { hasBin, kitRoot, log, pruneMuskatImages } from "./util.mjs";
+import { canSkipImageBuild, hasBin, kitRoot, log, pruneMuskatImages } from "./util.mjs";
 
 export const BRIDGE_IMAGE = "muscat-pk-bridge";
 export const BRIDGE_CONTAINER = "muscat-pk-bridge-run";
@@ -53,6 +53,10 @@ function waitForPort(port, timeoutMs = 15_000) {
 }
 
 function ensureImage() {
+  if (canSkipImageBuild(BRIDGE_IMAGE)) {
+    log.step(`${BRIDGE_IMAGE} already built — skipping docker build`);
+    return;
+  }
   log.step(`docker build -t ${BRIDGE_IMAGE} (first run is slow, then cached)…`);
   const r = spawnSync("docker", ["build", "-t", BRIDGE_IMAGE, "-f", DOCKERFILE, BUILD_CONTEXT], { stdio: "inherit" });
   if (r.status !== 0) throw new Error("docker build failed (bridge image).");
@@ -63,19 +67,37 @@ function ensureImage() {
  * Build the image, preflight the port, and start the bridge container.
  * Returns true if bridge started, false if port was already in use (caller decides).
  */
-export async function startBridge({ zenohPort = null } = {}) {
+export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
   assertDockerReady();
 
   // remove our own stale container first, then check the host port is free
   spawnSync("docker", ["rm", "-f", BRIDGE_CONTAINER], { stdio: "ignore" });
   if (await isPortInUse(BRIDGE_PORT)) return false;
 
+  // Publishing a busy port makes `docker run` fail with a raw daemon error —
+  // say which port and keep the bridge up instead.
+  const busy = [];
+  for (const port of pluginPorts) {
+    if (await isPortInUse(port)) busy.push(port);
+  }
+  if (busy.length > 0) {
+    log.warn(
+      `declared plugin port(s) already in use on the host: ${busy.join(", ")} — ` +
+      `not published (the backend still listens inside the container).`,
+    );
+  }
+  const publishable = pluginPorts.filter((port) => !busy.includes(port));
+
   ensureImage();
 
   log.step("starting Socket.IO bridge container…");
+  // The backend joins THIS container's netns (--network container:), and a
+  // netns can only publish ports when its owner starts — so the plugin's
+  // declared ports have to be published here, not on the backend container.
   const portFlags = [
     "-p", `127.0.0.1:${BRIDGE_PORT}:${BRIDGE_PORT}`,
     ...(zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : []),
+    ...publishable.flatMap((port) => ["-p", `127.0.0.1:${port}:${port}`]),
   ];
   const up = spawnSync(
     "docker",
@@ -87,6 +109,8 @@ export async function startBridge({ zenohPort = null } = {}) {
   await waitForPort(BRIDGE_PORT);
   log.step(`Socket.IO bridge listening on ws://127.0.0.1:${BRIDGE_PORT}`);
   if (zenohPort) log.step(`Zenoh dev peer port published on :${zenohPort}`);
+  if (publishable.length > 0)
+    log.step(`plugin backend ports published on 127.0.0.1: ${publishable.join(", ")}`);
   return true;
 }
 

package/cli/src/build.mjs

@@ -227,7 +227,17 @@ export async function buildPlugin({ root, minify = false } = {}) {
   const pluginRoot = root ?? findPluginRoot();
   assertManifest(pluginRoot);
   const distDir = resolve(pluginRoot, "dist");
-  rmSync(distDir, { recursive: true, force: true });
+  try {
+    rmSync(distDir, { recursive: true, force: true });
+  } catch (err) {
+    if (err?.code !== "EACCES" && err?.code !== "EPERM") throw err;
+    // 이전 버전이 컨테이너를 root로 돌려 남긴 dist/ — 한 번만 정리하면 된다
+    throw new Error(
+      `Permission denied when deleting dist/ (${err.path ?? distDir}).\n` +
+      `The previous build left files owned by root. Please clean it up once:\n` +
+      `  sudo rm -rf ${distDir}`,
+    );
+  }
   mkdirSync(distDir, { recursive: true });
 
   const manifest = JSON.parse(readFileSync(resolve(pluginRoot, "manifest.json"), "utf8"));

package/cli/src/cpp.mjs

@@ -3,7 +3,7 @@
 // Used by dev:back (interactive dev loop) and build (export the binary into the ZIP).
 import { spawnSync } from "node:child_process";
 import { dirname } from "node:path";
-import { hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
 
@@ -15,6 +15,10 @@ export function assertDockerReady() {
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
 export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null } = {}) {
+  if (canSkipImageBuild(image)) {
+    log.step(`${image} already built — skipping docker build`);
+    return;
+  }
   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] : [];
@@ -54,7 +58,7 @@ export function cmakeBuild(root, { image = CPP_DEV_IMAGE, buildType = "Debug", a
   log.step(label);
   const r = spawnSync(
     "docker",
-    ["run", "--rm", ...platformFlags, "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
+    ["run", "--rm", ...dockerUserFlags(), ...platformFlags, "-v", `${root}:/plugin`, "-w", "/plugin", actualImage, "bash", "-lc", script],
     { cwd: root, stdio: "inherit" },
   );
   if (r.status !== 0) throw new Error(`cmake build failed${arch ? ` (${arch})` : ""}.`);

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)}`);
@@ -133,6 +134,8 @@ export async function runDev(args = []) {
     zenohPort: remoteRobot && !proxyEndpoint && !usesHostNetwork()
       ? Number(process.env.MUSCAT_ZENOH_PORT)
       : null,
+    // Linux uses --network host, so the ports are already on the host.
+    pluginPorts: usesHostNetwork() ? [] : portRanges,
   });
 
   if (!bridgeStarted) {

package/cli/src/devBack.mjs

@@ -10,12 +10,13 @@
 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,
+  publishPortFlags,
   startPortContractMonitor,
 } from "./ports.mjs";
 import {
@@ -108,6 +109,10 @@ async function runPython(root, portRanges) {
     !useHostNet && !bridgeContainer && !proxyEndpoint && zenohPort
       ? ["-p", `${zenohPort}:${zenohPort}`]
       : [];
+  // Standalone dev:back owns its netns, so it publishes its own declared ports.
+  // Under `dev` the bridge owns the netns and published them already.
+  const pluginPortFlags =
+    !useHostNet && !bridgeContainer ? publishPortFlags(portRanges) : [];
   const hostGatewayFlags = useHostNet || bridgeContainer
     ? []
     : ["--add-host", "host.docker.internal:host-gateway"];
@@ -142,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,
+    ["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,
@@ -151,7 +156,7 @@ async function runPython(root, portRanges) {
     { 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: [zenohPort] });
 
   log.step("pip install requirements + watchfiles (in container)…");
   docker(["exec", container, "bash", "-lc",
@@ -440,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, "-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)…");
@@ -521,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, "-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…");
@@ -580,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", "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,44 @@ 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 === "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 +224,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 +244,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)

package/cli/src/mcp.mjs

@@ -22,8 +22,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import ts from "typescript";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { kitRoot, kitVersion, findPluginRoot, venvPython } from "./util.mjs";
@@ -111,10 +112,28 @@ function findStorySource(name) {
 /* -------------------------------------------------------------------------- */
 
 // Split the README on headings and keyword-score each section.
+// Headings inside fenced code blocks (```…```) don't count — a column-0
+// Python comment would otherwise start a bogus section.
+function splitSections(text) {
+  const sections = [];
+  let current = [];
+  let inFence = false;
+  for (const line of text.split("\n")) {
+    if (/^\s*```/.test(line)) inFence = !inFence;
+    if (!inFence && /^#{1,4} /.test(line) && current.length) {
+      sections.push(current.join("\n"));
+      current = [];
+    }
+    current.push(line);
+  }
+  if (current.length) sections.push(current.join("\n"));
+  return sections;
+}
+
 function searchReadme(query) {
   if (!existsSync(TEMPLATE_README)) return [];
   const text = readFileSync(TEMPLATE_README, "utf8");
-  const sections = text.split(/\n(?=#{1,4} )/);
+  const sections = splitSections(text);
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
 
   return sections
@@ -243,6 +262,39 @@ ${script}
   return { data };
 }
 
+/* -------------------------------------------------------------------------- */
+/* client registration — `muscat-pk mcp --install <client>`                    */
+/* -------------------------------------------------------------------------- */
+
+// Claude Code needs no install step: `muscat-pk new` scaffolds a project-level
+// .mcp.json. Codex only reads the global ~/.codex/config.toml, so we append
+// the server block there (idempotent).
+export function installMcp(target) {
+  if (target !== "codex") {
+    throw new Error(
+      `Unknown --install target ${JSON.stringify(target ?? "")} — supported: "codex". ` +
+        "(Claude Code works out of the box via the scaffolded .mcp.json.)",
+    );
+  }
+  const cfgDir = join(homedir(), ".codex");
+  const cfgPath = join(cfgDir, "config.toml");
+  const existing = existsSync(cfgPath) ? readFileSync(cfgPath, "utf8") : "";
+  if (/^\s*\[mcp_servers\.muscat\]/m.test(existing)) {
+    console.log(`Codex already has the muscat MCP server registered (${cfgPath}) — nothing to do.`);
+    return;
+  }
+  // ponytail: Windows Codex spawns without a shell, so it needs the .cmd shim.
+  const command = process.platform === "win32" ? "muscat-pk.cmd" : "muscat-pk";
+  mkdirSync(cfgDir, { recursive: true });
+  const sep = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  appendFileSync(
+    cfgPath,
+    `${sep}[mcp_servers.muscat]\ncommand = "${command}"\nargs = ["mcp"]\n`,
+  );
+  console.log(`Registered the muscat MCP server for Codex → ${cfgPath}`);
+  console.log("Restart Codex (or start a new session) to pick it up.");
+}
+
 /* -------------------------------------------------------------------------- */
 /* server                                                                      */
 /* -------------------------------------------------------------------------- */
@@ -348,7 +400,10 @@ export async function runMcp() {
       description:
         "Search the Muscat plugin-author README for how to use useRb(), rb.pub/sub/action/serve, " +
         "rb.toast/alert/confirm/prompt, useRbFormData/useRbSave (save/restore form data through the " +
-        "host), manifest.json, contribution points, and backend runtimes (Python/C++/ROS2). IMPORTANT: " +
+        "host), manifest.json (including the \"variables\" declaration for the pyfm variable picker — " +
+        "names require the RBP_ prefix), program variables & executor state (ctx.get_variable/" +
+        "set_variable/executor_state/check_stop), contribution points, and backend runtimes " +
+        "(Python/C++/ROS2). IMPORTANT: " +
         "the backend pattern depends on the contribution point — search 'which backend pattern' before " +
         "writing py/main.py. Only a program.panel command uses PluginProgramContext; a toolbar/move.panel " +
         "plugin controls the robot with the SDK (RBManipulateSDK/RBAmrSDK) directly.",

package/cli/src/new.mjs

@@ -65,6 +65,9 @@ function printNewSuccess({ targetName, type, pm }) {
   log.info(`  ${color.cyan("muscat-pk dev")}      ${color.dim("# preview in mini-Muscat + back end")}`);
   log.info(`  ${color.cyan("muscat-pk build")}    ${color.dim("# build + distributable ZIP")}`);
   log.info("");
+  log.info(color.dim("AI assistant? Claude Code reads the scaffolded .mcp.json;"));
+  log.info(color.dim(`Codex users run ${color.cyan("muscat-pk mcp --install codex")} once.`));
+  log.info("");
 }
 
 // Build the manifest runtime object for a given type choice + plugin slug.