@rainbow-robotics/muscat-plugin-kit 0.1.2-dev.9 → 0.10.1-dev.1

package/cli/src/type.mjs

@@ -1,21 +1,23 @@
 // muscat-pk type change — switch an existing plugin's backend type.
-//   python ↔ ros2.  python→ros2 adds the ros2_ws/ overlay; ros2→python flips
-//   the manifest type and leaves ros2_ws/ in place (never deletes user code).
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { createInterface } from "node:readline/promises";
-import { basename, resolve } from "node:path";
-import { findPluginRoot, log } from "./util.mjs";
-import { applyTokens, deriveNames, overlayRos2 } from "./new.mjs";
+//   python | cpp | ros2 (rclpy) | ros2-cpp (rclcpp).
+//   Adds the matching backend overlay; never deletes existing user code
+//   (e.g. ros2_ws/ or cpp/ are left in place when switching away).
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { findPluginRoot, log, prompt, templatesDir } from "./util.mjs";
+import {
+  TYPE_CHOICES,
+  applyTokens,
+  copyTemplate,
+  deriveNames,
+  overlayCpp,
+  overlayRos2,
+  prepareCppIde,
+  runtimeForChoice,
+} from "./new.mjs";
 
-const TYPES = ["python", "ros2"];
-
-async function prompt(question, fallback) {
-  if (!process.stdin.isTTY) return fallback;
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = (await rl.question(question)).trim();
-  rl.close();
-  return answer || fallback;
-}
+const TYPES = Object.keys(TYPE_CHOICES);
 
 function readManifest(root) {
   const path = resolve(root, "manifest.json");
@@ -23,45 +25,77 @@ function readManifest(root) {
   return { path, json: JSON.parse(readFileSync(path, "utf8")) };
 }
 
+// Derive the current `--type`-style key from a manifest runtime block.
+function currentTypeKey(runtime) {
+  if (runtime?.type === "ros2") return runtime.rosClient === "rclcpp" ? "ros2-cpp" : "ros2";
+  return runtime?.type ?? "python";
+}
+
+const isCpp = (key) => key === "cpp" || key === "ros2-cpp";
+
+async function offerReadme(root, toCpp, force, tokens) {
+  const lang = toCpp ? "C++" : "Python";
+  const answer = force ? "y" : await prompt(`Replace README.md with the ${lang} backend version? (current file kept as README.md.bak) [y/N]: `, "n");
+  if (!/^y/i.test(answer)) {
+    log.info(`README.md kept — to swap it later: muscat-pk type change --to <type> --readme`);
+    return;
+  }
+  const tmp = mkdtempSync(join(tmpdir(), "muscat-pk-readme-"));
+  try {
+    await copyTemplate(resolve(templatesDir, toCpp ? "readme-cpp" : "common"), tmp);
+    applyTokens(tmp, tokens);
+    const readme = resolve(root, "README.md");
+    if (existsSync(readme)) copyFileSync(readme, resolve(root, "README.md.bak"));
+    copyFileSync(join(tmp, "README.md"), readme);
+    log.ok(`README.md → ${lang} version${existsSync(resolve(root, "README.md.bak")) ? " (previous file: README.md.bak)" : ""}`);
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
 export async function runType(args) {
-  // accept `type change`, `type`, `type --to ros2`
+  // accept `type change`, `type`, `type --to ros2-cpp`
   const sub = args[0];
   const toFlagIdx = args.indexOf("--to");
   let to = toFlagIdx >= 0 ? args[toFlagIdx + 1] : undefined;
 
   const root = findPluginRoot();
   const { path, json } = readManifest(root);
-  const current = json.runtime?.type ?? "python";
+  const current = currentTypeKey(json.runtime);
 
   if (sub && sub !== "change") {
-    log.warn(`unknown subcommand '${sub}'. Usage: muscat-pk type change [--to python|ros2]`);
+    log.warn(`unknown subcommand '${sub}'. Usage: muscat-pk type change [--to python|cpp|ros2|ros2-cpp] [--readme]`);
   }
 
   if (!to) {
-    console.log(`\n현재 타입: ${current}`);
-    console.log("변경할 타입을 선택하세요:");
+    console.log(`\nCurrent type: ${current}`);
+    console.log("Select the new type:");
     console.log("  1) Python");
-    console.log("  2) ROS2(rclpy)");
-    const choice = await prompt("\n선택 [1/2]: ", "");
-    to = choice === "1" ? "python" : choice === "2" ? "ros2" : undefined;
+    console.log("  2) C++");
+    console.log("  3) ROS2 (rclpy / Python)");
+    console.log("  4) ROS2 (rclcpp / C++)");
+    const choice = await prompt("\nChoice [1/2/3/4]: ", "");
+    to = { "1": "python", "2": "cpp", "3": "ros2", "4": "ros2-cpp" }[choice];
   }
 
   if (!TYPES.includes(to)) {
-    throw new Error(`invalid type. choose python or ros2.`);
+    throw new Error(`invalid type. choose python | cpp | ros2 | ros2-cpp.`);
   }
   if (to === current) {
     log.info(`already '${current}' — nothing to change.`);
     return;
   }
 
-  if (to === "ros2") {
-    const { slug, pluginName, pluginClass, pluginId } = deriveNames(root);
+  const runtimeChoice = TYPE_CHOICES[to];
+  const { dir, slug, pluginName, pluginClass, pluginId } = deriveNames(root);
+
+  if (runtimeChoice.type === "ros2") {
     if (existsSync(resolve(root, "ros2_ws"))) {
       log.warn("ros2_ws/ already exists — keeping it, only flipping manifest type.");
     } else {
-      log.step("adding ros2_ws/ overlay");
-      overlayRos2(root, slug);
-      applyTokens(root, {
+      log.step(`adding ros2_ws/ overlay (${runtimeChoice.rosClient})`);
+      await overlayRos2(root, slug, runtimeChoice.rosClient);
+      applyTokens(resolve(root, "ros2_ws"), {
         __PLUGIN_ID__: pluginId,
         __PLUGIN_NAME__: pluginName,
         __PLUGIN_SLUG__: slug,
@@ -69,14 +103,39 @@ export async function runType(args) {
         __RUNTIME_TYPE__: "ros2",
       });
     }
+  } else if (runtimeChoice.type === "cpp") {
+    if (existsSync(resolve(root, "cpp"))) {
+      log.warn("cpp/ already exists — keeping it, only flipping manifest type.");
+    } else {
+      log.step("adding cpp/ overlay");
+      await overlayCpp(root);
+      applyTokens(resolve(root, "cpp"), {
+        __PLUGIN_ID__: pluginId,
+        __PLUGIN_NAME__: pluginName,
+        __PLUGIN_SLUG__: slug,
+        __PLUGIN_CLASS__: pluginClass,
+        __RUNTIME_TYPE__: "cpp",
+      });
+    }
   } else {
-    // ros2 → python
-    if (existsSync(resolve(root, "ros2_ws"))) {
-      log.warn("ros2_ws/ left in place (not deleted). Remove it manually if unused.");
+    // → python. Leave any ros2_ws/ or cpp/ in place (never delete user code).
+    if (existsSync(resolve(root, "ros2_ws")) || existsSync(resolve(root, "cpp"))) {
+      log.warn("existing backend dir left in place (not deleted). Remove it manually if unused.");
     }
   }
 
-  json.runtime = { ...json.runtime, type: to };
+  json.runtime = runtimeForChoice(runtimeChoice, slug);
   writeFileSync(path, JSON.stringify(json, null, 2) + "\n");
   log.ok(`${basename(root)} type: ${current} → ${to}`);
+  if (isCpp(to)) await prepareCppIde(root, runtimeChoice);
+
+  if (isCpp(current) !== isCpp(to)) {
+    await offerReadme(root, isCpp(to), args.includes("--readme"), {
+      __PLUGIN_ID__: pluginId,
+      __PLUGIN_NAME__: pluginName,
+      __PLUGIN_DIR__: dir,
+      __PLUGIN_SLUG__: slug,
+      __PLUGIN_CLASS__: pluginClass,
+    });
+  }
 }

package/cli/src/uninstall.mjs

@@ -0,0 +1,81 @@
+// muscat-pk uninstall - remove the installed CLI, whether npm-global or S3 binary.
+import { execSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { KIT_PUBLISHED_NAME, isNpmGlobalInstall, log, parseArgs } from "./util.mjs";
+
+const isBinaryMode = typeof Bun !== "undefined";
+
+function uninstallNpmGlobal() {
+  log.step(`npm uninstall -g ${KIT_PUBLISHED_NAME}`);
+  execSync(`npm uninstall -g ${KIT_PUBLISHED_NAME}`, { stdio: "inherit" });
+  log.ok("Global npm package removed.");
+}
+
+function uninstallBinary() {
+  const execPath = process.execPath;
+  log.step(`Removing binary: ${execPath}`);
+
+  if (process.platform === "win32") {
+    const ps = `Start-Sleep -Milliseconds 500; Remove-Item -Force '${execPath}'`;
+    spawn("powershell", ["-NoProfile", "-Command", ps], {
+      detached: true,
+      stdio: "ignore",
+    }).unref();
+    log.ok("Binary will be removed after this process exits.");
+    return;
+  }
+
+  try {
+    rmSync(execPath, { force: true });
+  } catch (err) {
+    if (err?.code !== "EACCES" && err?.code !== "EPERM") throw err;
+    log.info("  sudo is required...");
+    const result = spawnSync("sudo", ["rm", "-f", execPath], { stdio: "inherit" });
+    if (result.status !== 0) throw new Error(`sudo rm failed: ${execPath}`);
+  }
+
+  const parent = dirname(execPath);
+  for (const shim of ["muscat-pk.cmd", "muscat-pk.ps1"]) {
+    rmSync(join(parent, shim), { force: true });
+  }
+
+  log.ok("Binary removed.");
+}
+
+export async function runUninstall(args = []) {
+  const opts = parseArgs(args, { booleans: ["help"] });
+
+  if (opts.help) {
+    log.info(
+      [
+        "Usage: muscat-pk uninstall",
+        "",
+        "Removes the installed muscat-pk CLI.",
+        "  npm global install  -> npm uninstall -g @rainbow-robotics/muscat-plugin-kit",
+        "  S3 binary install   -> remove the muscat-pk executable",
+      ].join("\n"),
+    );
+    return;
+  }
+
+  if (isBinaryMode) {
+    uninstallBinary();
+    return;
+  }
+
+  if (isNpmGlobalInstall()) {
+    uninstallNpmGlobal();
+    return;
+  }
+
+  const localBin = process.argv[1] || "";
+  if (localBin.includes(`${join("node_modules", ".bin")}`) || existsSync(join(process.cwd(), "package.json"))) {
+    log.warn("This muscat-pk appears to be running from a project/local install.");
+    log.warn("Remove it from the project package manager instead, for example:");
+    log.warn(`  npm uninstall ${KIT_PUBLISHED_NAME}`);
+    return;
+  }
+
+  throw new Error("Could not determine install mode. Remove muscat-pk manually from your PATH.");
+}

package/cli/src/update.mjs

@@ -1,52 +1,381 @@
-// muscat-pk update — update the JS plugin kit and host-provided UI contract.
-import { execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { findPluginRoot, KIT_PUBLISHED_NAME, log, parseArgs } from "./util.mjs";
+// muscat-pk update — update the CLI itself AND the plugin project's JS deps.
+//
+// Three install modes are handled:
+//   binary  : Bun self-contained binary downloaded from S3
+//             → re-download from S3, replace process.execPath
+//   npm -g  : globally installed Node.js package
+//             → npm install -g @rainbow-robotics/muscat-plugin-kit@<tag>
+//   local   : plugin project's node_modules (fallback)
+//             → <pm> add @rainbow-robotics/muscat-plugin-kit@<tag>
+//
+// After updating the CLI itself, also bumps the plugin project's local deps
+// and migrates the project structure if it's outdated (src/ → ui/, root main.py → py/).
+import { execSync, spawn, spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { agentsMd, CLAUDE_MD, MCP_JSON } from "./ai-rules.mjs";
+import { checkProject, formatProjectCheck } from "./projectCheck.mjs";
+import {
+  compareKitVersions, findPluginRoot, isLocalKitInstall, KIT_PUBLISHED_NAME, kitVersion, log, parseArgs, prompt,
+  resolveLocalCliBin,
+} from "./util.mjs";
 
 const PLUGIN_UI_PACKAGE = "@rainbow-robotics/plugin-ui";
+const PREVIEW_HOST_PACKAGE = "@rainbow-robotics/preview-host";
+const S3_BASE = "https://rainbow-deploy.s3.ap-northeast-2.amazonaws.com/muscat-plugin-kit";
+
+const isBinaryMode = typeof Bun !== "undefined";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
 
 function detectPm(root) {
   try {
     const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
     if (pkg.packageManager) return pkg.packageManager.split("@")[0];
-  } catch {
-    /* ignore */
-  }
+  } catch { /* ignore */ }
   if (existsSync(resolve(root, "pnpm-lock.yaml"))) return "pnpm";
   if (existsSync(resolve(root, "yarn.lock"))) return "yarn";
   if (existsSync(resolve(root, "bun.lockb"))) return "bun";
   return "npm";
 }
 
-export async function runUpdate(args = []) {
-  const root = findPluginRoot();
+async function fetchText(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+  return (await res.text()).trim();
+}
+
+async function fetchBinary(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+function s3BinaryName() {
+  const platform = process.platform;
+  const arch = process.arch;
+  const plat = platform === "win32" ? "win" : platform === "darwin" ? "darwin" : "linux";
+  const cpu = arch === "arm64" ? "arm64" : "x64";
+  const ext = platform === "win32" ? ".exe" : "";
+  return `muscat-pk-${plat}-${cpu}${ext}`;
+}
+
+async function resolveS3Version(tag) {
+  const pointer = tag === "dev" ? "dev-version.txt" : "latest-version.txt";
+  return fetchText(`${S3_BASE}/${pointer}`);
+}
+
+// ── self-update: binary ───────────────────────────────────────────────────────
+
+async function updateBinary(tag) {
+  const version = await resolveS3Version(tag);
+  const current = kitVersion();
+  if (version === current) {
+    log.ok(`Already up to date (v${current})`);
+    return;
+  }
+
+  const binaryName = s3BinaryName();
+  const url = `${S3_BASE}/v${version}/${binaryName}`;
+  log.step(`Downloading binary: v${current} → v${version}`);
+
+  const data = await fetchBinary(url);
+  const execPath = process.execPath;
+
+  if (process.platform === "win32") {
+    // Windows: cannot overwrite a running .exe — write .new then schedule replacement
+    const newPath = execPath + ".new";
+    writeFileSync(newPath, data);
+
+    // PowerShell snippet that waits for this process to exit, then renames
+    const ps = `Start-Sleep -Milliseconds 500; Move-Item -Force '${newPath}' '${execPath}'`;
+    spawn("powershell", ["-NoProfile", "-Command", ps], {
+      detached: true,
+      stdio: "ignore",
+    }).unref();
+
+    log.ok(`v${version} will be applied on next run.`);
+  } else {
+    // macOS / Linux: 실행 중인 파일에 덮어쓰면 Linux 는 ETXTBSY. 같은 디렉토리에 쓰고 rename 으로 바꿔치기한다.
+    const newPath = execPath + ".new";
+    writeFileSync(newPath, data);
+    chmodSync(newPath, 0o755);
+    try {
+      renameSync(newPath, execPath);
+    } catch (err) {
+      if (err?.code !== "EACCES" && err?.code !== "EPERM") throw err;
+      log.info("  sudo is required...");
+      const r = spawnSync("sudo", ["mv", "-f", newPath, execPath], { stdio: "inherit" });
+      if (r.status !== 0) throw new Error(`sudo mv failed: ${execPath}`);
+    }
+    log.ok(`Updated to v${version}.`);
+  }
+}
+
+// ── self-update: npm global ───────────────────────────────────────────────────
+
+function updateNpmGlobal(tag) {
+  log.step(`npm install -g ${KIT_PUBLISHED_NAME}@${tag}`);
+  execSync(`npm install -g ${KIT_PUBLISHED_NAME}@${tag}`, { stdio: "inherit" });
+  log.ok("Global CLI updated.");
+}
+
+// ── project structure migration ───────────────────────────────────────────────
+
+function detectOldStructure(root) {
+  const issues = [];
+
+  // src/ exists (old UI dir) or vite.config references src/content.tsx
+  const hasSrcDir = existsSync(resolve(root, "src"));
+  const hasUiDir  = existsSync(resolve(root, "ui"));
+  const viteRef   = (() => {
+    try {
+      return readFileSync(resolve(root, "vite.config.ts"), "utf8").includes("src/content.tsx");
+    } catch { return false; }
+  })();
+  if ((hasSrcDir || viteRef) && !hasUiDir) {
+    issues.push({ kind: "src→ui", desc: "src/  →  ui/  (+ vite.config.ts, tsconfig.json)" });
+  }
+
+  if (existsSync(resolve(root, "main.py")) && !existsSync(resolve(root, "py"))) {
+    issues.push({ kind: "main→py", desc: "main.py  →  py/main.py" });
+  }
+  if (existsSync(resolve(root, "backend"))) {
+    issues.push({ kind: "backend→py", desc: "backend/  →  py/" });
+  }
+  return issues;
+}
+
+async function migrateStructure(root, issues) {
+  log.warn("This plugin project's structure is outdated:");
+  for (const issue of issues) log.info("  • " + issue.desc);
+  log.warn("Files will be moved and modified. Back up or commit your work before proceeding.");
+
+  const answer = await prompt("Migrate project structure? [y/N] ");
+  if (answer.toLowerCase() !== "y") {
+    log.info("Structure migration skipped.");
+    return;
+  }
+
+  for (const issue of issues) {
+    if (issue.kind === "src→ui") {
+      if (existsSync(resolve(root, "src"))) {
+        renameSync(resolve(root, "src"), resolve(root, "ui"));
+        log.ok("src/  →  ui/");
+      }
+
+      const vitePath = resolve(root, "vite.config.ts");
+      if (existsSync(vitePath)) {
+        writeFileSync(vitePath, readFileSync(vitePath, "utf8").replace(/["']src\/content\.tsx["']/g, '"ui/content.tsx"'));
+        log.ok("vite.config.ts entry updated");
+      }
+      const tscPath = resolve(root, "tsconfig.json");
+      if (existsSync(tscPath)) {
+        writeFileSync(tscPath, readFileSync(tscPath, "utf8").replace(/"src"/g, '"ui"'));
+        log.ok("tsconfig.json include updated");
+      }
+    }
+
+    if (issue.kind === "main→py") {
+      mkdirSync(resolve(root, "py"), { recursive: true });
+      renameSync(resolve(root, "main.py"), resolve(root, "py", "main.py"));
+      log.ok("main.py  →  py/main.py");
+    }
+
+    if (issue.kind === "backend→py") {
+      renameSync(resolve(root, "backend"), resolve(root, "py"));
+      log.ok("backend/  →  py/");
+      const pyReqs = resolve(root, "py", "requirements.txt");
+      const rootReqs = resolve(root, "requirements.txt");
+      if (existsSync(pyReqs) && !existsSync(rootReqs)) {
+        renameSync(pyReqs, rootReqs);
+        log.ok("py/requirements.txt  →  requirements.txt (project root)");
+      }
+    }
+  }
+
+  log.ok("Migration complete. Run `muscat-pk build` to verify.");
+}
+
+// ── plugin project local deps ─────────────────────────────────────────────────
+
+// The three packages are released together on one version, so preview-host moves with the other
+// two — left behind, an old pin keeps serving a preview that no longer matches plugin-ui.
+function updateLocalDeps(root, tag) {
   const pm = detectPm(root);
-  const opts = parseArgs(args);
-
-  const range =
-    opts._[0] ||
-    opts.version ||
-    opts["muscat-plugin-kit"] ||
-    opts["plugin-ui"] ||
-    "latest";
-  const list = [
-    `${KIT_PUBLISHED_NAME}@${range}`,
-    `${PLUGIN_UI_PACKAGE}@${range}`,
-  ];
-
-  const cmd =
-    pm === "npm"
-      ? `npm install ${list.join(" ")}`
-      : pm === "yarn"
-        ? `yarn add ${list.join(" ")}`
-        : `${pm} add ${list.join(" ")}`;
-
-  log.step(`${pm}: ${list.join(", ")}`);
-  try {
-    execSync(cmd, { cwd: root, stdio: "inherit" });
-    log.ok("kit packages updated");
+  let pkg = {};
+  try {
+    pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
+  } catch { /* ignore */ }
+  const listed = (name) => Boolean(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
+  const names = [KIT_PUBLISHED_NAME, PLUGIN_UI_PACKAGE, ...(listed(PREVIEW_HOST_PACKAGE) ? [PREVIEW_HOST_PACKAGE] : [])];
+  const isDev = (name) => Boolean(pkg.devDependencies?.[name]);
+  const add = (list, dev) => {
+    const flag = dev ? " -D" : "";
+    return pm === "npm" ? `npm install${flag} ${list.join(" ")}` : `${pm} add${flag} ${list.join(" ")}`;
+  };
+  // Keep each package in the section it is already in (yarn/pnpm `add` would move devDeps).
+  const cmds = [false, true]
+    .map((dev) => [names.filter((n) => isDev(n) === dev).map((n) => `${n}@${tag}`), dev])
+    .filter(([list]) => list.length)
+    .map(([list, dev]) => add(list, dev));
+
+  log.step(`Updating plugin local deps (${pm}): ${names.map((n) => `${n}@${tag}`).join(", ")}`);
+  try {
+    for (const cmd of cmds) execSync(cmd, { cwd: root, stdio: "inherit" });
+    log.ok("Local deps updated.");
   } catch {
-    log.warn("update failed (offline?). Run manually:\n  " + cmd);
+    log.warn("Local deps update failed (offline?). Run manually:\n  " + cmds.join("\n  "));
+  }
+}
+
+const PROJECT_CHECK_HEADER = "This project needs changes for the updated plugin-ui. Fix these before `muscat-pk dev` / `build`:";
+
+function reportProject(root) {
+  const lines = formatProjectCheck(checkProject(root));
+  if (!lines.length) return;
+  log.warn(PROJECT_CHECK_HEADER);
+  for (const l of lines) log.info(l);
+}
+
+/** `muscat-pk update:check` — the post-update project check, run by the freshly installed kit. */
+export async function runUpdateCheck() {
+  reportProject(findPluginRoot());
+}
+
+// Prefer the kit update just installed: it knows the plugin-ui it shipped with, this process may not.
+function checkProjectAfterUpdate(root) {
+  const localBin = resolveLocalCliBin(root);
+  let localVersion = "";
+  try {
+    localVersion = JSON.parse(readFileSync(resolve(localBin, "../../../package.json"), "utf8")).version;
+  } catch { /* no local kit */ }
+  if (localBin && localVersion && compareKitVersions(localVersion, kitVersion()) >= 0) {
+    const runtime = isBinaryMode ? "node" : process.execPath;
+    const r = spawnSync(runtime, [localBin, "update:check"], { cwd: root, stdio: "inherit" });
+    if (!r.error && r.status === 0) return;
+  }
+  reportProject(root);
+}
+
+// ── AI agent files ────────────────────────────────────────────────────────────
+// Projects made before `new` scaffolded these have no MCP server or agent rules, so an agent asked
+// to fix the update can't call check_project. Only missing files are written; edited ones stay.
+
+function pluginNameOf(root) {
+  try {
+    const { name } = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
+    if (typeof name === "string") return name;
+    if (name && typeof name === "object") return name.en ?? Object.values(name)[0] ?? "";
+  } catch { /* fall through */ }
+  return "";
+}
+
+function ensureAiFiles(root) {
+  const files = {
+    ".mcp.json": () => MCP_JSON,
+    "AGENTS.md": () => agentsMd({ pluginName: pluginNameOf(root) || "Plugin" }),
+    "CLAUDE.md": () => CLAUDE_MD,
+  };
+  for (const [file, content] of Object.entries(files)) {
+    if (existsSync(resolve(root, file))) continue;
+    writeFileSync(resolve(root, file), content());
+    log.ok(`${file} added (MCP server / AI agent rules)`);
+  }
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+async function resolveTag(explicitTag) {
+  if (explicitTag) return explicitTag;
+
+  const current = kitVersion();
+  const isDevVersion = current.includes("-dev.");
+
+  if (!isDevVersion) return "latest";
+
+  const answer = await prompt(
+    `You are on a dev version (v${current}).\n` +
+    `  [1] Stay on dev  — update to latest dev build\n` +
+    `  [2] Switch to stable — update to latest stable release\n` +
+    `Choice [1/2, default: 1]: `
+  );
+  return answer.trim() === "2" ? "latest" : "dev";
+}
+
+export async function runUpdate(args = []) {
+  const opts = parseArgs(args, { booleans: ["global"] });
+  const explicitTag = opts._[0] || opts.version || opts.tag || "";
+  const tag = await resolveTag(explicitTag);
+
+  // 지금 도는 게 프로젝트의 로컬 설치면 그 프로젝트만 건드린다. 이 머신의 다른
+  // 프로젝트들이 쓰는 글로벌 CLI까지 같이 올리려면 --global을 명시해야 한다.
+  const runningLocal = isLocalKitInstall() || process.env.MUSCAT_PK_UPDATE_PROJECT_ONLY === "1";
+
+  // 1. Update the CLI itself
+  if (!runningLocal || opts.global) {
+    if (isBinaryMode) {
+      log.step("Updating binary…");
+      try {
+        await updateBinary(tag);
+      } catch (err) {
+        log.warn(`Binary update failed: ${err.message}`);
+      }
+    } else {
+      const isGlobal = (() => {
+        try {
+          const prefix = execSync("npm prefix -g", { encoding: "utf8" }).trim();
+          return (
+            // Unix: {prefix}/bin/muscat-pk
+            existsSync(join(prefix, "bin", "muscat-pk")) ||
+            // Windows npm: {prefix}/muscat-pk.cmd (no bin/ subdir)
+            existsSync(join(prefix, "muscat-pk.cmd")) ||
+            existsSync(join(prefix, "bin", "muscat-pk.cmd"))
+          );
+        } catch { return false; }
+      })();
+
+      if (isGlobal) {
+        try {
+          updateNpmGlobal(tag);
+        } catch (err) {
+          log.warn(`Global CLI update failed: ${err.message}`);
+        }
+      }
+    }
+  } else {
+    log.info("Local install detected — updating this project only. Pass --global to also update the global CLI.");
+  }
+
+  // 2. Plugin project: structure migration + local deps
+  let root;
+  try {
+    root = findPluginRoot();
+  } catch {
+    // Not inside a plugin project — skip
+    return;
+  }
+
+  try {
+    const structureIssues = detectOldStructure(root);
+    if (structureIssues.length > 0) {
+      await migrateStructure(root, structureIssues);
+    }
+  } catch (err) {
+    log.warn(`Structure check failed: ${err.message}`);
+  }
+
+  try {
+    ensureAiFiles(root);
+  } catch (err) {
+    log.warn(`AI agent files: ${err.message}`);
+  }
+
+  updateLocalDeps(root, tag);
+
+  try {
+    checkProjectAfterUpdate(root);
+  } catch (err) {
+    log.warn(`Project check failed: ${err.message}`);
   }
 }