@zhuoyuezs/ml-platform 0.1.0 → 0.1.3

package/scripts/lib.js

@@ -7,7 +7,9 @@ const path = require("path");
 const { spawnSync } = require("child_process");
 const RELEASE_POLICY = require("../release-policy.json");
 
-const PACKAGE_NAME = "@zhuoyuezs/ml-platform";
+const PACKAGE_CONFIG = require("../package.json");
+const PACKAGE_NAME = PACKAGE_CONFIG.name;
+const PACKAGE_VERSION = PACKAGE_CONFIG.version;
 const CLI_NAME = "ml-platform";
 const SKILL_NAME = "feature-management";
 const RELEASE_SCHEMA = "data_platform.ml_platform_release/v2";
@@ -23,6 +25,12 @@ if (RELEASE_POLICY.schema_version !== "data_platform.ml_platform_release_policy/
 const FORBIDDEN_DIRECTORIES = new Set(RELEASE_POLICY.forbidden_directories);
 const FORBIDDEN_FILES = new Set(RELEASE_POLICY.forbidden_files);
 const FORBIDDEN_SUFFIXES = new Set(RELEASE_POLICY.forbidden_suffixes);
+const FORBIDDEN_CONTENT_PATTERNS = (RELEASE_POLICY.forbidden_content_patterns || []).map((item) => {
+  if (!item || typeof item.name !== "string" || typeof item.pattern !== "string") {
+    throw new Error("release policy 包含无效内容规则");
+  }
+  return { name: item.name, pattern: new RegExp(item.pattern, "i") };
+});
 
 function parseOptions(args) {
   const options = {
@@ -31,7 +39,10 @@ function parseOptions(args) {
     upgrade: false,
     allowDowngrade: false,
     prewarm: true,
+    backupUnmanaged: false,
+    summary: true,
   };
+  let outputFlag = null;
   const valueFlags = new Map([
     ["--agent", "agent"],
     ["--scope", "scope"],
@@ -54,6 +65,16 @@ function parseOptions(args) {
       options.allowDowngrade = true;
     } else if (arg === "--no-prewarm") {
       options.prewarm = false;
+    } else if (arg === "--backup-unmanaged") {
+      options.backupUnmanaged = true;
+    } else if (arg === "--summary") {
+      if (outputFlag === "json") throw new Error("--summary 与 --json 不能同时使用");
+      outputFlag = "summary";
+      options.summary = true;
+    } else if (arg === "--json") {
+      if (outputFlag === "summary") throw new Error("--summary 与 --json 不能同时使用");
+      outputFlag = "json";
+      options.summary = false;
     } else {
       throw new Error(`未知参数: ${arg}`);
     }
@@ -68,6 +89,7 @@ function resolveInstallPaths(options = {}) {
   if (!["user", "project"].includes(scope)) throw new Error(`不支持的安装作用域: ${scope}`);
 
   let skillsDir;
+  let projectDir = null;
   if (options.skillsDir) {
     skillsDir = path.resolve(expandHome(options.skillsDir));
   } else if (agent === "codex" && scope === "user") {
@@ -76,7 +98,7 @@ function resolveInstallPaths(options = {}) {
       : path.join(os.homedir(), ".codex");
     skillsDir = path.join(codexHome, "skills");
   } else if (agent === "codex" && scope === "project") {
-    const projectDir = path.resolve(expandHome(options.projectDir || process.cwd()));
+    projectDir = path.resolve(expandHome(options.projectDir || process.cwd()));
     if (!fs.existsSync(projectDir)) throw new Error(`Codex 项目目录不存在: ${projectDir}`);
     if (!fs.statSync(projectDir).isDirectory()) throw new Error(`Codex 项目路径不是目录: ${projectDir}`);
     skillsDir = path.join(projectDir, ".agents", "skills");
@@ -98,6 +120,7 @@ function resolveInstallPaths(options = {}) {
   return {
     agent,
     scope,
+    projectDir,
     skillsDir,
     target,
     record: path.join(skillsDir, `.${SKILL_NAME}.ml-platform.json`),
@@ -123,6 +146,12 @@ function loadRelease(packageRoot = PACKAGE_ROOT) {
     throw new Error("release policy 摘要与 release manifest 不匹配");
   }
   if (!isSemver(release.release_version)) throw new Error("release_version 不是有效 SemVer");
+  const requirements = release.runtime_requirements;
+  if (!requirements || requirements.node !== ">=18"
+      || !Array.isArray(requirements.os)
+      || requirements.os.join(",") !== "darwin,linux") {
+    throw new Error("release manifest 缺少有效 runtime requirements");
+  }
   const skill = release.skills && release.skills[SKILL_NAME];
   if (!skill || skill.path !== `skills/${SKILL_NAME}` || !isSha256(skill.sha256)
       || !isSemver(skill.revision) || typeof skill.requires_cli !== "string") {
@@ -179,6 +208,13 @@ function verifyPackage(packageRoot = PACKAGE_ROOT) {
   assertAllowedClient(clientRoot);
   rejectForbiddenTree(skillRoot, "Skill");
   rejectForbiddenTree(clientRoot, "business client");
+  rejectForbiddenContent([
+    ...listFiles(skillRoot),
+    ...listFiles(clientRoot),
+    ...["README.md", "DEVELOPMENT.md"]
+      .map((name) => path.join(packageRoot, name))
+      .filter((file) => fs.existsSync(file)),
+  ], "release payload");
   if (fs.existsSync(path.join(skillRoot, "runtime")) || fs.existsSync(path.join(skillRoot, "scripts"))) {
     throw new Error("Skill 不得包含 CLI runtime 或 wrapper");
   }
@@ -247,6 +283,29 @@ function doctor(options = {}, packageRoot = PACKAGE_ROOT) {
   let expectedRelease = null;
   const hasCompletePackage = fs.existsSync(path.join(packageRoot, "checksums.json"))
     && fs.existsSync(path.join(packageRoot, "skills", SKILL_NAME));
+
+  // Check for legacy Python Skill before proceeding
+  if (!fs.existsSync(paths.record)) {
+    const legacy = detectLegacySkill(paths.target);
+    if (legacy) {
+      const markers = Object.entries(legacy).filter(([_, v]) => v).map(([k]) => k).join(", ");
+      return {
+        ok: false,
+        error: `检测到旧 Python Skill (${markers})`,
+        remediation: buildInstallCommand(
+          paths,
+          options,
+          "install",
+          packageVersion(packageRoot),
+          ["--backup-unmanaged"],
+        ),
+        legacy_skill_detected: true,
+        legacy_markers: legacy,
+        skill_root: paths.target,
+      };
+    }
+  }
+
   try {
     if (hasCompletePackage) {
       expectedRelease = verifyPackage(packageRoot).release;
@@ -296,11 +355,31 @@ function doctor(options = {}, packageRoot = PACKAGE_ROOT) {
     actual: matchingShim ?? pathMatches[0] ?? null,
     remediation: pathOk ? null : `将 ${paths.binDir} 加入 PATH，然后重启 Agent 会话`,
   });
-  if (options.apiUrl) {
-    const apiHealth = runApiHealth(paths.dispatcher, options.apiUrl);
-    checks.push({ name: "platform_api", ok: apiHealth.ok, detail: apiHealth.detail });
+  const apiTarget = resolveEffectiveApiTarget(options, paths.dispatcher);
+  if (apiTarget.error) {
+    checks.push({
+      name: "platform_api",
+      ok: false,
+      source: apiTarget.source,
+      detail: apiTarget.error,
+    });
+  } else if (apiTarget.apiUrl) {
+    const apiHealth = runApiHealth(paths.dispatcher, apiTarget.apiUrl);
+    checks.push({
+      name: "platform_api",
+      ok: apiHealth.ok,
+      source: apiTarget.source,
+      api_url: apiTarget.apiUrl,
+      detail: apiHealth.detail,
+    });
   } else {
-    checks.push({ name: "platform_api", ok: null, skipped: true, reason: "未提供 --api-url" });
+    checks.push({
+      name: "platform_api",
+      ok: null,
+      skipped: true,
+      source: null,
+      reason: "未通过 --api-url、ML_PLATFORM_API_URL 或 configure 配置 API 地址",
+    });
   }
   return {
     ok: checks.every((check) => check.ok !== false),
@@ -320,18 +399,70 @@ function install(options = {}, packageRoot = PACKAGE_ROOT) {
   return withInstallLock(paths.lock, () => installLocked(options, packageRoot, verified, paths));
 }
 
+function detectLegacySkill(skillPath) {
+  if (!pathEntryExists(skillPath) || !fs.lstatSync(skillPath).isDirectory()) return null;
+  const markers = {
+    pythonWheel: fs.existsSync(path.join(skillPath, "assets", "wheels"))
+      && fs.readdirSync(path.join(skillPath, "assets", "wheels")).some(f => f.endsWith(".whl")),
+    runtimeJson: fs.existsSync(path.join(skillPath, "assets", "wheels", "runtime.json")),
+    bootstrapScript: fs.existsSync(path.join(skillPath, "scripts", "bootstrap.py")),
+    installScript: fs.existsSync(path.join(skillPath, "scripts", "install.py")),
+    oldLauncher: fs.existsSync(path.join(skillPath, "scripts", "data-platform-demo"))
+      || fs.existsSync(path.join(skillPath, "scripts", "ml-platform")),
+  };
+  const hasAnyMarker = Object.values(markers).some(Boolean);
+  return hasAnyMarker ? markers : null;
+}
+
+function backupUnmanagedSkill(skillPath, skillsDir, legacy) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  let suffix = 0;
+  let backupPath;
+  do {
+    const kind = legacy ? "legacy-backup" : "unmanaged-backup";
+    const backupName = `.${SKILL_NAME}.${kind}.${timestamp}${suffix ? `-${suffix}` : ""}`;
+    backupPath = path.join(skillsDir, backupName);
+    suffix += 1;
+  } while (pathEntryExists(backupPath));
+  fs.renameSync(skillPath, backupPath);
+  return backupPath;
+}
+
 function installLocked(options, packageRoot, verified, paths) {
   const previousRecord = fs.existsSync(paths.record) ? fs.readFileSync(paths.record) : null;
   const current = safeReadInstallationRecord(paths.record, paths);
-  const targetExists = fs.existsSync(paths.target);
-  if (targetExists && !current) {
-    throw new Error(`目标 Skill 不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.target}`);
+  const targetExists = pathEntryExists(paths.target);
+  const legacy = targetExists && !current ? detectLegacySkill(paths.target) : null;
+  const backingUpUnmanaged = Boolean(targetExists && !current && options.backupUnmanaged);
+
+  if (options.migrateLegacy && !legacy) {
+    throw new Error(`目标 Skill 不是旧 Python Skill 或不存在: ${paths.target}`);
+  }
+
+  if (targetExists && !current && !backingUpUnmanaged) {
+    if (legacy && !options.backupUnmanaged) {
+      const markers = Object.entries(legacy).filter(([_, v]) => v).map(([k]) => k).join(", ");
+      throw new Error(
+        `目标 Skill 包含旧 Python runtime 标记 (${markers})，拒绝覆盖: ${paths.target}\n` +
+        `  迁移方法: 使用 --backup-unmanaged 或运行 'ml-platform migrate' 先备份旧 Skill`
+      );
+    } else if (fs.lstatSync(paths.target).isSymbolicLink()) {
+      throw new Error(
+        `目标 Skill 路径是未托管的符号链接，拒绝覆盖: ${paths.target}\n` +
+        "  处理方法: 确认后使用 --backup-unmanaged 备份该链接并安装正式 Skill"
+      );
+    } else if (!legacy) {
+      throw new Error(
+        `目标 Skill 不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.target}\n` +
+        "  处理方法: 确认后使用 --backup-unmanaged 备份原目录"
+      );
+    }
   }
   const sharedRuntime = safeReadRuntimeRecord(paths.runtimeRecord);
-  if (fs.existsSync(paths.installRoot) && !sharedRuntime) {
+  if (pathEntryExists(paths.installRoot) && !sharedRuntime) {
     throw new Error(`持久 CLI 目录不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.installRoot}`);
   }
-  if (fs.existsSync(paths.shim) && (!current || sha256File(paths.shim) !== current.shim.sha256)
+  if (pathEntryExists(paths.shim) && (!current || sha256File(paths.shim) !== current.shim.sha256)
       && (!sharedRuntime || !shimTargetsDispatcher(paths.shim, paths.dispatcher))) {
     throw new Error(`CLI shim 不受 ${PACKAGE_NAME} 管理，拒绝覆盖: ${paths.shim}`);
   }
@@ -360,7 +491,7 @@ function installLocked(options, packageRoot, verified, paths) {
     return installationResult("unchanged", paths, verified.release, current);
   }
 
-  if ((targetExists || (sharedRuntime && !sharedRuntimeMatches)) && !options.upgrade) {
+  if (((targetExists && !backingUpUnmanaged) || (sharedRuntime && !sharedRuntimeMatches)) && !options.upgrade) {
     throw new Error("已存在不同版本或摘要；升级时请使用 upgrade 或 install --upgrade");
   }
   const installedVersion = current ? current.release_version : sharedRuntime && sharedRuntime.release_version;
@@ -383,6 +514,8 @@ function installLocked(options, packageRoot, verified, paths) {
   let hadState = false;
   let hadSkill = false;
   let hadShim = false;
+  let legacyBackupPath = null;
+  let legacyMoved = false;
   try {
     stagePersistentInstall(stagedInstall, packageRoot, verified);
     fs.cpSync(verified.skillRoot, stagedSkill, { recursive: true, errorOnExist: true });
@@ -391,19 +524,23 @@ function installLocked(options, packageRoot, verified, paths) {
     }
     writeShim(shimTemporary, paths.dispatcher);
 
-    if (fs.existsSync(paths.installRoot)) {
+    if (backingUpUnmanaged) {
+      legacyBackupPath = backupUnmanagedSkill(paths.target, paths.skillsDir, Boolean(legacy));
+      legacyMoved = true;
+    }
+    if (pathEntryExists(paths.installRoot)) {
       fs.renameSync(paths.installRoot, stateBackup);
       hadState = true;
     }
     fs.renameSync(stagedInstall, paths.installRoot);
     stateMoved = true;
-    if (fs.existsSync(paths.target)) {
+    if (pathEntryExists(paths.target)) {
       fs.renameSync(paths.target, skillBackup);
       hadSkill = true;
     }
     fs.renameSync(stagedSkill, paths.target);
     skillMoved = true;
-    if (fs.existsSync(paths.shim)) {
+    if (pathEntryExists(paths.shim)) {
       fs.renameSync(paths.shim, shimBackup);
       hadShim = true;
     }
@@ -419,19 +556,32 @@ function installLocked(options, packageRoot, verified, paths) {
     if (hadState) removeOwnedDirectory(stateBackup, paths.stateDir, ".backup.");
     if (hadSkill) removeOwnedDirectory(skillBackup, paths.skillsDir, `.${SKILL_NAME}.backup.`);
     if (hadShim) fs.rmSync(shimBackup, { force: true });
-    return installationResult(current || targetExists ? "upgraded" : "installed", paths, verified.release, record);
+    const result = installationResult(
+      options.migrateLegacy ? "migrated" : (current || (targetExists && !backingUpUnmanaged) ? "upgraded" : "installed"),
+      paths,
+      verified.release,
+      record,
+    );
+    if (legacyBackupPath) {
+      if (legacy) result.legacy_skill_backup = legacyBackupPath;
+      else result.unmanaged_skill_backup = legacyBackupPath;
+    }
+    return result;
   } catch (error) {
-    if (shimMoved && fs.existsSync(paths.shim)) fs.rmSync(paths.shim, { force: true });
-    if (hadShim && fs.existsSync(shimBackup)) fs.renameSync(shimBackup, paths.shim);
-    if (skillMoved && fs.existsSync(paths.target)) removeOwnedDirectory(paths.target, paths.skillsDir, SKILL_NAME);
-    if (hadSkill && fs.existsSync(skillBackup)) fs.renameSync(skillBackup, paths.target);
-    if (stateMoved && fs.existsSync(paths.installRoot)) removeOwnedDirectory(paths.installRoot, paths.stateDir, "current");
-    if (hadState && fs.existsSync(stateBackup)) fs.renameSync(stateBackup, paths.installRoot);
+    if (shimMoved && pathEntryExists(paths.shim)) fs.rmSync(paths.shim, { force: true });
+    if (hadShim && pathEntryExists(shimBackup)) fs.renameSync(shimBackup, paths.shim);
+    if (skillMoved && pathEntryExists(paths.target)) removeOwnedDirectory(paths.target, paths.skillsDir, SKILL_NAME);
+    if (hadSkill && pathEntryExists(skillBackup)) fs.renameSync(skillBackup, paths.target);
+    if (legacyMoved && legacyBackupPath && pathEntryExists(legacyBackupPath) && !pathEntryExists(paths.target)) {
+      fs.renameSync(legacyBackupPath, paths.target);
+    }
+    if (stateMoved && pathEntryExists(paths.installRoot)) removeOwnedDirectory(paths.installRoot, paths.stateDir, "current");
+    if (hadState && pathEntryExists(stateBackup)) fs.renameSync(stateBackup, paths.installRoot);
     if (previousRecord === null) fs.rmSync(paths.record, { force: true });
     else fs.writeFileSync(paths.record, previousRecord);
-    if (fs.existsSync(shimTemporary)) fs.rmSync(shimTemporary, { force: true });
-    if (fs.existsSync(stateStaging)) removeOwnedDirectory(stateStaging, paths.stateDir, ".install.");
-    if (fs.existsSync(skillStaging)) removeOwnedDirectory(skillStaging, paths.skillsDir, `.${SKILL_NAME}.install.`);
+    if (pathEntryExists(shimTemporary)) fs.rmSync(shimTemporary, { force: true });
+    if (pathEntryExists(stateStaging)) removeOwnedDirectory(stateStaging, paths.stateDir, ".install.");
+    if (pathEntryExists(skillStaging)) removeOwnedDirectory(skillStaging, paths.skillsDir, `.${SKILL_NAME}.install.`);
     throw error;
   }
 }
@@ -442,6 +592,7 @@ function stagePersistentInstall(target, packageRoot, verified) {
   for (const name of ["main.js", "lib.js"]) {
     fs.copyFileSync(path.join(packageRoot, "scripts", name), path.join(target, "scripts", name));
   }
+  fs.copyFileSync(path.join(packageRoot, "package.json"), path.join(target, "package.json"));
   fs.chmodSync(path.join(target, "scripts", "main.js"), 0o755);
   fs.cpSync(verified.clientRoot, path.join(target, "runtime", "business-client"), {
     recursive: true,
@@ -591,6 +742,38 @@ function runApiHealth(dispatcher, apiUrl) {
   return runCliRuntime(dispatcher, ["--api-url", apiUrl.replace(/\/+$/, ""), "health"], false);
 }
 
+function resolveEffectiveApiTarget(
+  options,
+  dispatcher,
+  env = process.env,
+  runtime = runCliRuntime,
+) {
+  if (options.apiUrl && String(options.apiUrl).trim()) {
+    return { apiUrl: String(options.apiUrl).trim(), source: "argument" };
+  }
+  if (env.ML_PLATFORM_API_URL && String(env.ML_PLATFORM_API_URL).trim()) {
+    return { apiUrl: String(env.ML_PLATFORM_API_URL).trim(), source: "environment" };
+  }
+  const configured = runtime(dispatcher, ["show-config"], false);
+  if (!configured.ok) {
+    return {
+      apiUrl: null,
+      source: "saved_config",
+      error: `无法读取已保存的 API 配置: ${configured.detail || "未知错误"}`,
+    };
+  }
+  let payload;
+  try {
+    payload = JSON.parse(configured.detail);
+  } catch (_) {
+    return { apiUrl: null, source: "saved_config", error: "show-config 未返回有效 JSON" };
+  }
+  const apiUrl = payload && payload.effective && payload.effective.api_url;
+  return apiUrl
+    ? { apiUrl: String(apiUrl).trim(), source: "saved_config" }
+    : { apiUrl: null, source: null };
+}
+
 function checkTree(checks, name, root, expected) {
   if (!expected || !fs.existsSync(root)) {
     checks.push({ name, ok: false, error: `缺少安装目录或预期摘要: ${root}` });
@@ -618,6 +801,16 @@ function digestEquals(root, expected) {
   catch (_) { return false; }
 }
 
+function pathEntryExists(entry) {
+  try {
+    fs.lstatSync(entry);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
 function withInstallLock(lockPath, callback) {
   let descriptor;
   try {
@@ -684,6 +877,18 @@ function rejectForbiddenTree(root, label) {
   visit(root);
 }
 
+function rejectForbiddenContent(files, label) {
+  for (const file of files) {
+    if (!fs.statSync(file).isFile() || path.basename(file) === "release-policy.json") continue;
+    const text = fs.readFileSync(file, "utf8");
+    for (const rule of FORBIDDEN_CONTENT_PATTERNS) {
+      if (rule.pattern.test(text)) {
+        throw new Error(`${label} 包含禁止发布内容 ${rule.name}: ${file}`);
+      }
+    }
+  }
+}
+
 function treeDigest(root) {
   const files = listFiles(root);
   const hash = crypto.createHash("sha256");
@@ -782,35 +987,103 @@ function isSemver(value) {
   return typeof value === "string" && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
 }
 
+function parseSemver(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(value);
+  if (!match) throw new Error("无法比较无效 SemVer");
+  return {
+    core: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ? match[4].split(".") : null,
+  };
+}
+
 function compareSemver(left, right) {
-  if (!isSemver(left) || !isSemver(right)) throw new Error("无法比较无效 SemVer");
-  const a = left.split("-")[0].split(".").map(Number);
-  const b = right.split("-")[0].split(".").map(Number);
+  const aParsed = parseSemver(left);
+  const bParsed = parseSemver(right);
+  const a = aParsed.core;
+  const b = bParsed.core;
   for (let index = 0; index < 3; index += 1) {
     if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
   }
+  if (!aParsed.prerelease && !bParsed.prerelease) return 0;
+  if (!aParsed.prerelease) return 1;
+  if (!bParsed.prerelease) return -1;
+  const length = Math.max(aParsed.prerelease.length, bParsed.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    if (index >= aParsed.prerelease.length) return -1;
+    if (index >= bParsed.prerelease.length) return 1;
+    const leftPart = aParsed.prerelease[index];
+    const rightPart = bParsed.prerelease[index];
+    if (leftPart === rightPart) continue;
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+    if (leftNumeric && rightNumeric) return Number(leftPart) < Number(rightPart) ? -1 : 1;
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+    return leftPart < rightPart ? -1 : 1;
+  }
   return 0;
 }
 
 function versionSatisfies(version, range) {
-  const match = /^(>=\d+\.\d+\.\d+)\s+(<\d+\.\d+\.\d+)$/.exec(range);
+  const match = /^>=(\S+)\s+<(\S+)$/.exec(range);
   if (!match) return false;
-  return compareSemver(version, match[1].slice(2)) >= 0 && compareSemver(version, match[2].slice(1)) < 0;
+  return compareSemver(version, match[1]) >= 0 && compareSemver(version, match[2]) < 0;
+}
+
+function migrate(options = {}, packageRoot = PACKAGE_ROOT) {
+  return install({ ...options, backupUnmanaged: true, migrateLegacy: true }, packageRoot);
+}
+
+function packageVersion(packageRoot = PACKAGE_ROOT) {
+  try {
+    const release = readJson(path.join(packageRoot, "release.json"), "release manifest");
+    if (isSemver(release.release_version)) return release.release_version;
+  } catch (_) { /* source checkout may not have a generated release */ }
+  try {
+    const packageConfig = readJson(path.join(packageRoot, "package.json"), "package.json");
+    if (isSemver(packageConfig.version)) return packageConfig.version;
+  } catch (_) { /* use the package fallback */ }
+  return PACKAGE_VERSION;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function buildInstallCommand(paths, options, command, version, extraArgs = []) {
+  const args = [
+    "npm exec --yes --registry=https://registry.npmjs.org/",
+    `--package=${PACKAGE_NAME}@${version}`,
+    "--",
+    "ml-platform",
+    command,
+    "--agent", paths.agent,
+    "--scope", paths.scope,
+  ];
+  if (paths.projectDir) args.push("--project-dir", paths.projectDir);
+  if (options.skillsDir) args.push("--skills-dir", paths.skillsDir);
+  if (options.stateDir) args.push("--state-dir", paths.stateDir);
+  if (options.binDir) args.push("--bin-dir", paths.binDir);
+  args.push(...extraArgs);
+  return args.map((arg, index) => index < 2 ? arg : shellQuote(arg)).join(" ");
 }
 
 module.exports = {
   CHECKSUM_SCHEMA,
   CLI_NAME,
   PACKAGE_NAME,
+  PACKAGE_VERSION,
   RECORD_SCHEMA,
   RELEASE_SCHEMA,
   SKILL_NAME,
   compareSemver,
+  detectLegacySkill,
   doctor,
   install,
   listFiles,
   loadRelease,
+  migrate,
   parseOptions,
+  resolveEffectiveApiTarget,
   resolveInstallPaths,
   sha256File,
   status,