supacloud 0.3.0

package/README.md

@@ -0,0 +1,79 @@
+# supacloud
+
+Unified entrypoint that bundles both SupaCloud CLIs behind a single `supacloud` command.
+
+```
+supacloud cli   → @supacloud/cli    (project-scoped developer tools)
+supacloud admin → @supacloud/admin  (platform operations: install / SSH / tenant management)
+```
+
+## 安装
+
+```bash
+npm install -g supacloud
+supacloud --help
+```
+
+One-off execution:
+
+```bash
+npx supacloud cli status
+npx supacloud admin status
+```
+
+`supacloud` depends on both `@supacloud/cli` and `@supacloud/admin`, so installing
+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`).
+
+## 自动更新
+
+`supacloud cli ...` and `supacloud admin ...` check the npm `latest` dist-tag before dispatch.
+When a newer `@supacloud/cli` or `@supacloud/admin` version exists, the dispatcher runs it with
+`npm exec --package <pkg>@<latest> -- <bin> ...args`. If the registry is unavailable, it falls
+back to the dependency version bundled with the installed `supacloud` package.
+
+Disable the latest check when you need a pinned local version:
+
+```bash
+SUPACLOUD_NO_AUTO_UPDATE=1 supacloud cli status
+# or
+SUPACLOUD_AUTO_UPDATE=0 supacloud admin status
+```
+
+Use `SUPACLOUD_NPM_REGISTRY` or `npm_config_registry` to point the check at a registry mirror.
+
+## 用法
+
+```bash
+supacloud cli status
+supacloud cli project get
+supacloud cli gateway routes --ref <ref>
+
+supacloud admin status
+supacloud admin project list
+supacloud admin ssh ping
+```
+
+Each subcommand accepts its own `--help`:
+
+```bash
+supacloud cli --help
+supacloud admin --help
+```
+
+## 上下文
+
+`supacloud cli` auto-links the current project from `.env`:
+
+- `SUPABASE_URL` / `SUPACLOUD_API_URL`
+- `SUPABASE_SERVICE_ROLE_KEY` / `SUPACLOUD_API_TOKEN`
+
+`supacloud admin` expects platform context:
+
+- `SUPACLOUD_HOST` + `SUPACLOUD_SSH_KEY` / `SUPACLOUD_SSH_PASS`
+- `SUPACLOUD_API_URL` + `SUPACLOUD_API_TOKEN`
+
+> Note: on hosts where SupaCloud is installed as a server, `/usr/local/bin/supacloud`
+> is the compiled management-api binary (the server process). This npm package's
+> `supacloud` command targets developer/operator workflows and is meant for your
+> local machine, not the server's process namespace.

package/dist/index.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, parse } from "node:path";
+import { fileURLToPath } from "node:url";
+var require2 = createRequire(import.meta.url);
+var SUBCOMMANDS = {
+  cli: { pkg: "@supacloud/cli", bin: "supacloud-cli", desc: "项目级 CLI（开发者工具）" },
+  admin: { pkg: "@supacloud/admin", bin: "supacloud-admin", desc: "平台运维 CLI（安装/SSH/租户管理）" }
+};
+function resolveSubpackageEntry(pkgName) {
+  try {
+    return require2.resolve(pkgName);
+  } catch {
+    return null;
+  }
+}
+var COMMAND = "supacloud";
+var DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org/";
+var AUTO_UPDATE_TIMEOUT_MS = 2000;
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readPackageVersion(packageJsonPath) {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    if (isRecord(parsed) && typeof parsed.version === "string")
+      return parsed.version;
+  } catch {}
+  return null;
+}
+function packageJsonMatches(path, pkgName) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return isRecord(parsed) && parsed.name === pkgName;
+  } catch {
+    return false;
+  }
+}
+function findPackageJsonFromEntry(entry, pkgName) {
+  let dir = dirname(entry);
+  const root = parse(dir).root;
+  while (dir && dir !== root) {
+    const candidate = join(dir, "package.json");
+    if (existsSync(candidate) && packageJsonMatches(candidate, pkgName)) {
+      return candidate;
+    }
+    dir = dirname(dir);
+  }
+  return null;
+}
+function resolveInstalledPackage(pkgName) {
+  const entry = resolveSubpackageEntry(pkgName);
+  if (!entry)
+    return null;
+  let packageJsonPath = null;
+  try {
+    packageJsonPath = require2.resolve(`${pkgName}/package.json`);
+  } catch {
+    packageJsonPath = findPackageJsonFromEntry(entry, pkgName);
+  }
+  return {
+    entry,
+    version: packageJsonPath ? readPackageVersion(packageJsonPath) : null
+  };
+}
+function isAutoUpdateDisabled(env = process.env) {
+  const noAutoUpdate = env.SUPACLOUD_NO_AUTO_UPDATE;
+  if (noAutoUpdate && !["0", "false", "no", "off"].includes(noAutoUpdate.toLowerCase())) {
+    return true;
+  }
+  const autoUpdate = env.SUPACLOUD_AUTO_UPDATE;
+  return Boolean(autoUpdate && ["0", "false", "no", "off"].includes(autoUpdate.toLowerCase()));
+}
+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}/`;
+}
+function buildLatestMetadataUrl(pkgName, registry = DEFAULT_NPM_REGISTRY) {
+  const base = registry.endsWith("/") ? registry : `${registry}/`;
+  const encodedName = encodeURIComponent(pkgName).replace(/^%40/, "@");
+  return `${base}${encodedName}/latest`;
+}
+async function fetchLatestVersion(pkgName, env = process.env, fetchImpl) {
+  const activeFetch = fetchImpl ?? globalThis.fetch;
+  if (!activeFetch)
+    return null;
+  const controller = new AbortController;
+  const timeout = setTimeout(() => controller.abort(), AUTO_UPDATE_TIMEOUT_MS);
+  try {
+    const response = await activeFetch(buildLatestMetadataUrl(pkgName, getNpmRegistry(env)), {
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok)
+      return null;
+    const metadata = await response.json();
+    if (isRecord(metadata) && typeof metadata.version === "string") {
+      return metadata.version;
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function parseSemver(version) {
+  const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match)
+    return null;
+  return {
+    main: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] ?? null
+  };
+}
+function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b)
+    return left.localeCompare(right);
+  for (let i = 0;i < 3; i += 1) {
+    if (a.main[i] !== b.main[i])
+      return a.main[i] > b.main[i] ? 1 : -1;
+  }
+  if (a.prerelease === b.prerelease)
+    return 0;
+  if (!a.prerelease)
+    return 1;
+  if (!b.prerelease)
+    return -1;
+  return a.prerelease.localeCompare(b.prerelease);
+}
+function isNewerVersion(latestVersion, currentVersion) {
+  if (!currentVersion)
+    return true;
+  return compareSemver(latestVersion, currentVersion) > 0;
+}
+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);
+  if (!isAutoUpdateDisabled(env)) {
+    const latestVersion = await fetchLatest(target.pkg, env);
+    if (latestVersion && isNewerVersion(latestVersion, installed?.version ?? null)) {
+      return {
+        mode: "latest",
+        command: options.npmCommand ?? "npm",
+        args: ["exec", "--yes", "--package", `${target.pkg}@${latestVersion}`, "--", target.bin, ...forwardedArgs],
+        shell: (options.platform ?? process.platform) === "win32"
+      };
+    }
+  }
+  if (!installed) {
+    throw new Error(`${target.pkg} 未安装，且无法从 npm registry 获取最新版。`);
+  }
+  return {
+    mode: "local",
+    command: options.nodePath ?? process.execPath,
+    args: [installed.entry, ...forwardedArgs],
+    shell: false
+  };
+}
+function buildHelp() {
+  const subs = Object.entries(SUBCOMMANDS).map(([name, sub]) => `  ${name.padEnd(6)} ${sub.desc}`).join(`
+`);
+  return `
+╔═══════════════════════════════════════════════════════════╗
+║  supacloud                                               ║
+║  统一入口 · 路由到项目级 CLI 与平台运维 CLI              ║
+╚═══════════════════════════════════════════════════════════╝
+
+用法
+
+  ${COMMAND} <子命令> [args...]
+  ${COMMAND} --help
+
+子命令
+
+${subs}
+
+示例
+
+  ${COMMAND} cli status
+  ${COMMAND} cli project get
+  ${COMMAND} cli gateway routes --ref <ref>
+  ${COMMAND} admin status
+  ${COMMAND} admin project list
+  ${COMMAND} admin ssh ping
+
+每次执行子命令时默认检查 npm latest；发现 @supacloud/cli 或
+@supacloud/admin 有新版本时会自动通过 npm exec 运行最新版。
+离线时回退到本地依赖。设置 SUPACLOUD_NO_AUTO_UPDATE=1 可禁用。
+`;
+}
+async function run(args) {
+  const sub = args[0];
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    console.error(buildHelp());
+    process.exit(0);
+  }
+  const target = SUBCOMMANDS[sub];
+  if (!target) {
+    console.error(`❌ 未知子命令: ${sub}
+`);
+    console.error(buildHelp());
+    process.exit(1);
+  }
+  const plan = await createLaunchPlan(target, args.slice(1));
+  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);
+  });
+}
+var isMainEntry = (() => {
+  try {
+    return fileURLToPath(import.meta.url) === process.argv[1];
+  } catch {
+    return false;
+  }
+})();
+if (isMainEntry) {
+  run(process.argv.slice(2)).catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`❌ supacloud 启动失败: ${message}`);
+    process.exit(1);
+  });
+}
+export {
+  resolveSubpackageEntry,
+  resolveInstalledPackage,
+  isNewerVersion,
+  isAutoUpdateDisabled,
+  getNpmRegistry,
+  fetchLatestVersion,
+  createLaunchPlan,
+  compareSemver,
+  buildLatestMetadataUrl,
+  buildHelp,
+  SUBCOMMANDS
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "supacloud",
+  "version": "0.3.0",
+  "description": "Unified entrypoint: `supacloud cli` and `supacloud admin` in one command",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "supacloud": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "build": "bun build src/index.ts --outdir dist --target node",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "supacloud",
+    "cli",
+    "admin",
+    "supabase",
+    "umbrella"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zuohuadong/supacloud.git",
+    "directory": "packages/supacloud"
+  },
+  "dependencies": {
+    "@supacloud/cli": "^0.8.0",
+    "@supacloud/admin": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^6.0.3"
+  }
+}