supacloud 0.5.3 → 0.6.0

package/README.md

@@ -25,19 +25,22 @@ npx --package supacloud supacloudctl admin status
 it gives you the full toolset. You can still install either CLI on its own
 (`@supacloud/cli` exposes `supacloud-cli`, `@supacloud/admin` exposes `supacloud-admin`).
 
-## 更新提示
+## 更新检查
 
-`supacloudctl cli ...` and `supacloudctl admin ...` check the npm `latest` dist-tag before dispatch.
-When a newer package exists, the dispatcher prints an update notice but still runs the dependency
-version bundled with the installed `supacloud` package. It never downloads or executes a newer
-operator CLI implicitly.
+Normal `supacloudctl cli ...` and `supacloudctl admin ...` dispatch is local-only and does not
+contact npm. Run an explicit check when needed:
 
-Disable the latest check when you need a pinned local version:
+```bash
+supacloudctl check-update
+supacloudctl check-update cli
+supacloudctl check-update admin
+```
+
+The dispatcher never downloads or executes a newer operator CLI implicitly. To opt into the old
+notify-before-dispatch behavior, set:
 
 ```bash
-SUPACLOUD_NO_AUTO_UPDATE=1 supacloudctl cli status
-# or
-SUPACLOUD_AUTO_UPDATE=0 supacloudctl admin status
+SUPACLOUD_AUTO_UPDATE=1 supacloudctl cli status
 ```
 
 Use `SUPACLOUD_NPM_REGISTRY` or `npm_config_registry` to point the check at a registry mirror.
@@ -67,10 +70,11 @@ supacloudctl admin --help
 
 - `SUPABASE_URL` / `SUPACLOUD_API_URL`
 - `SUPABASE_SERVICE_ROLE_KEY` / `SUPACLOUD_API_TOKEN`
+- `SUPACLOUD_PROJECT_REF` when it cannot be inferred from a managed `<ref>.api.*` hostname
 
 `supacloudctl admin` expects platform context:
 
-- `SUPACLOUD_HOST` + `SUPACLOUD_SSH_KEY` / `SUPACLOUD_SSH_PASS`
+- `SUPACLOUD_HOST` + `SUPACLOUD_SSH_KEY` / `SUPACLOUD_SSH_PASS` + `SUPACLOUD_SSH_HOST_FINGERPRINT`
 - `SUPACLOUD_API_URL` + `SUPACLOUD_API_TOKEN`
 
 > Note: `/usr/local/bin/supacloud` is the compiled management-api server binary.

package/dist/index.js

@@ -75,6 +75,11 @@ function isAutoUpdateDisabled(env = process.env) {
   const autoUpdate = env.SUPACLOUD_AUTO_UPDATE;
   return Boolean(autoUpdate && ["0", "false", "no", "off"].includes(autoUpdate.toLowerCase()));
 }
+function isAutoUpdateEnabled(env = process.env) {
+  if (isAutoUpdateDisabled(env))
+    return false;
+  return Boolean(env.SUPACLOUD_AUTO_UPDATE);
+}
 function getNpmRegistry(env = process.env) {
   const registry = env.SUPACLOUD_NPM_REGISTRY || env.npm_config_registry || env.NPM_CONFIG_REGISTRY || DEFAULT_NPM_REGISTRY;
   return registry.endsWith("/") ? registry : `${registry}/`;
@@ -139,21 +144,23 @@ function isNewerVersion(latestVersion, currentVersion) {
     return true;
   return compareSemver(latestVersion, currentVersion) > 0;
 }
+async function updateNoticeForLaunch(target, installed, env, fetchLatest) {
+  if (!isAutoUpdateEnabled(env))
+    return;
+  const latestVersion = await fetchLatest(target.pkg, env);
+  if (!latestVersion || !isNewerVersion(latestVersion, installed.version))
+    return;
+  return installed.version ? `${target.pkg} ${latestVersion} 可用；当前固定使用已安装版本 ${installed.version}。请显式运行包管理器更新。` : `${target.pkg} ${latestVersion} 可用；已安装版本无法识别，请通过包管理器检查锁定版本。`;
+}
 async function createLaunchPlan(target, forwardedArgs, options = {}) {
   const env = options.env ?? process.env;
   const resolveInstalled = options.resolveInstalled ?? resolveInstalledPackage;
   const fetchLatest = options.fetchLatest ?? fetchLatestVersion;
   const installed = resolveInstalled(target.pkg);
-  let updateNotice;
-  if (!isAutoUpdateDisabled(env)) {
-    const latestVersion = await fetchLatest(target.pkg, env);
-    if (latestVersion && isNewerVersion(latestVersion, installed?.version ?? null)) {
-      updateNotice = installed?.version ? `${target.pkg} ${latestVersion} 可用；当前固定使用已安装版本 ${installed.version}。请显式运行包管理器更新。` : `${target.pkg} ${latestVersion} 可用；请先通过包管理器显式安装。`;
-    }
-  }
   if (!installed) {
     throw new Error(`${target.pkg} 未安装。请先通过包管理器显式安装固定版本。`);
   }
+  const updateNotice = await updateNoticeForLaunch(target, installed, env, fetchLatest);
   return {
     mode: "local",
     command: options.nodePath ?? process.execPath,
@@ -162,8 +169,42 @@ async function createLaunchPlan(target, forwardedArgs, options = {}) {
     ...updateNotice ? { updateNotice } : {}
   };
 }
+async function checkUpdate(target, options = {}) {
+  const env = options.env ?? process.env;
+  const resolveInstalled = options.resolveInstalled ?? resolveInstalledPackage;
+  const fetchLatest = options.fetchLatest ?? fetchLatestVersion;
+  const installed = resolveInstalled(target.pkg);
+  if (!installed)
+    return missingPackageCheck(target.pkg);
+  const latestVersion = await fetchLatest(target.pkg, env);
+  if (!latestVersion)
+    return unavailableRegistryCheck(target.pkg, installed.version);
+  return completedUpdateCheck(target.pkg, installed.version, latestVersion);
+}
+function missingPackageCheck(packageName) {
+  return { packageName, currentVersion: null, latestVersion: null, status: "not_installed" };
+}
+function unavailableRegistryCheck(packageName, currentVersion) {
+  return { packageName, currentVersion, latestVersion: null, status: "registry_unavailable" };
+}
+function completedUpdateCheck(packageName, currentVersion, latestVersion) {
+  const status = isNewerVersion(latestVersion, currentVersion) ? "update_available" : "up_to_date";
+  return { packageName, currentVersion, latestVersion, status };
+}
+function formatUpdateCheck(check) {
+  switch (check.status) {
+    case "update_available":
+      return `${check.packageName}: ${check.latestVersion} 可用（当前 ${check.currentVersion ?? "未知"}）`;
+    case "up_to_date":
+      return `${check.packageName}: 已是最新版本 ${check.currentVersion ?? check.latestVersion ?? "未知"}`;
+    case "not_installed":
+      return `${check.packageName}: 未安装`;
+    case "registry_unavailable":
+      return `${check.packageName}: 无法从 npm registry 获取版本信息`;
+  }
+}
 function buildHelp() {
-  const subs = Object.entries(SUBCOMMANDS).map(([name, sub]) => `  ${name.padEnd(6)} ${sub.desc}`).join(`
+  const subcommandHelp = Object.entries(SUBCOMMANDS).map(([name, sub]) => `  ${name.padEnd(6)} ${sub.desc}`).join(`
 `);
   return `
 ╔═══════════════════════════════════════════════════════════╗
@@ -174,11 +215,12 @@ function buildHelp() {
 用法
 
   ${COMMAND} <子命令> [args...]
+  ${COMMAND} check-update [cli|admin]
   ${COMMAND} --help
 
 子命令
 
-${subs}
+${subcommandHelp}
 
 示例
 
@@ -188,37 +230,56 @@ ${subs}
   ${COMMAND} admin status
   ${COMMAND} admin project list
   ${COMMAND} admin ssh ping
+  ${COMMAND} check-update
+  ${COMMAND} check-update cli
 
-每次执行子命令时默认检查 npm latest；发现新版本时只输出更新提示，
-始终运行已安装的固定版本。设置 SUPACLOUD_NO_AUTO_UPDATE=1 可禁用检查。
+普通分发默认不访问 npm，始终运行已安装的固定版本。
+使用 check-update 显式查询更新；SUPACLOUD_AUTO_UPDATE=1 可选择恢复分发前提示。
 `;
 }
+async function runUpdateCheckCommand(args) {
+  const targetName = args[1];
+  if (args.length > 2 || targetName && !SUBCOMMANDS[targetName]) {
+    console.error(`❌ 未知更新检查目标: ${targetName ?? ""}`);
+    process.exit(1);
+  }
+  const targets = targetName ? [SUBCOMMANDS[targetName]] : Object.values(SUBCOMMANDS);
+  const checks = await Promise.all(targets.map((target) => checkUpdate(target)));
+  for (const check of checks)
+    console.log(formatUpdateCheck(check));
+  const failed = checks.some((check) => ["registry_unavailable", "not_installed"].includes(check.status));
+  process.exit(failed ? 1 : 0);
+}
+async function dispatchSubcommand(target, forwardedArgs) {
+  const launchPlan = await createLaunchPlan(target, forwardedArgs);
+  if (launchPlan.updateNotice)
+    console.error(`ℹ️ ${launchPlan.updateNotice}`);
+  const childProcess = spawn(launchPlan.command, launchPlan.args, {
+    stdio: "inherit",
+    shell: launchPlan.shell
+  });
+  childProcess.on("close", (code) => process.exit(code ?? 1));
+  childProcess.on("error", (error) => {
+    console.error(`❌ 启动 ${target.pkg} 失败: ${error.message}`);
+    process.exit(1);
+  });
+}
 async function run(args) {
-  const sub = args[0];
-  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+  const subcommandName = args[0];
+  if (!subcommandName || subcommandName === "--help" || subcommandName === "-h" || subcommandName === "help") {
     console.error(buildHelp());
     process.exit(0);
   }
-  const target = SUBCOMMANDS[sub];
+  if (subcommandName === "check-update")
+    await runUpdateCheckCommand(args);
+  const target = SUBCOMMANDS[subcommandName];
   if (!target) {
-    console.error(`❌ 未知子命令: ${sub}
+    console.error(`❌ 未知子命令: ${subcommandName}
 `);
     console.error(buildHelp());
     process.exit(1);
   }
-  const plan = await createLaunchPlan(target, args.slice(1));
-  if (plan.updateNotice) {
-    console.error(`ℹ️ ${plan.updateNotice}`);
-  }
-  const child = spawn(plan.command, plan.args, {
-    stdio: "inherit",
-    shell: plan.shell
-  });
-  child.on("close", (code) => process.exit(code ?? 1));
-  child.on("error", (err) => {
-    console.error(`❌ 启动 ${target.pkg} 失败: ${err.message}`);
-    process.exit(1);
-  });
+  await dispatchSubcommand(target, args.slice(1));
 }
 function isMainModule(moduleUrl, argvEntry = process.argv[1]) {
   if (!argvEntry)
@@ -241,11 +302,13 @@ export {
   resolveInstalledPackage,
   isNewerVersion,
   isMainModule,
+  isAutoUpdateEnabled,
   isAutoUpdateDisabled,
   getNpmRegistry,
   fetchLatestVersion,
   createLaunchPlan,
   compareSemver,
+  checkUpdate,
   buildLatestMetadataUrl,
   buildHelp,
   SUBCOMMANDS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supacloud",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Unified entrypoint: `supacloudctl cli` and `supacloudctl admin` in one command",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,8 +31,8 @@
     "directory": "packages/supacloud"
   },
   "dependencies": {
-    "@supacloud/cli": "^0.9.2",
-    "@supacloud/admin": "^0.3.2"
+    "@supacloud/cli": "^0.11.0",
+    "@supacloud/admin": "^0.5.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",