@zleap-ai/app-cli 0.0.0-stage → 0.10.1

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @zleap-ai/app-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+zleapOS 云开发命令行工具 `zleap-app` 的 npm 发行版。安装时 npm 只会下载与你的系统匹配的那一个预编译二进制
+（`@zleap-ai/app-cli-<os>-<arch>`），不需要 Go 环境。
+
+```bash
+npx @zleap-ai/app-cli                 # 查看版本与命令列表
+npm i -D @zleap-ai/app-cli            # 作为项目开发依赖（脚手架默认已加）
+npx zleap-app check ./dist
+```
+
+支持平台：macOS（arm64 / x64）、Linux（x64 / arm64）、Windows（x64 / arm64）。
+
+## 常用命令
+
+| 阶段     | 命令                                                                 |
+| -------- | -------------------------------------------------------------------- |
+| 登录     | `zleap-app auth login --target https://os.example.com --app-key <appid>`（appid 在云开发控制台「创建应用」获得） |
+| 检查打包 | `zleap-app check <目录或zip>`、`zleap-app pack <目录> --output app.zip` |
+| 上传安装 | `zleap-app publish <目录或zip>`、`zleap-app install <app_id>`         |
+| 资源准备 | `zleap-app prepare <app_id> --version-id <id> --request-id <32位hex>` |
+| 诊断     | `zleap-app diagnose <app_id>`、`zleap-app runtime-logs <app_id>`      |
+| 版本     | `zleap-app versions / update / rollback / uninstall <app_id>`         |
+| 上架     | `zleap-app market-publish <package_id> --app-key <key>`              |
+| MCP      | `zleap-app mcp serve --workspace <绝对路径> --target <OS 地址>`       |
+
+完整说明见 zleapOS 云开发文档「从开发到上线」。
+
+## 排障
+
+- **找不到平台包**：安装时不要使用 `--no-optional` / `--omit=optional`；跨平台拷贝 `node_modules` 后需重新安装。
+- **自行构建的二进制**：设置环境变量 `ZLEAP_APP_BINARY=/path/to/zleap-app`，入口会直接使用它。
+- 退出码与原生 CLI 一致：`2` 为普通失败，`6` 为 `COMMIT_UNKNOWN`（结果未知，先查询原操作，不要直接重试）。

package/bin/zleap-app.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict';
+// zleap-app 的 npm 入口：找到当前平台的预编译二进制，原样透传参数、标准输入输出与退出码。
+// MCP（zleap-app mcp serve）依赖 stdio 透传，这里不能向 stdout 写任何额外内容。
+
+const { spawn } = require('node:child_process');
+const { resolveBinary, BinaryNotFoundError } = require('../lib/resolve.js');
+
+let binary;
+try {
+  binary = resolveBinary();
+} catch (error) {
+  if (error instanceof BinaryNotFoundError) {
+    process.stderr.write(`zleap-app: ${error.message}\n`);
+    process.exit(127);
+  }
+  throw error;
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit', windowsHide: true });
+
+const forward = (signal) => {
+  if (!child.killed) child.kill(signal);
+};
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => forward(signal));
+}
+
+child.on('error', (error) => {
+  process.stderr.write(`zleap-app: 无法启动 ${binary}：${error.message}\n`);
+  process.exit(127);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/lib/resolve.js

@@ -0,0 +1,80 @@
+'use strict';
+// 解析当前平台对应的 zleap-app 预编译二进制。
+// 查找顺序：ZLEAP_APP_BINARY 环境变量 → 平台子包（optionalDependencies）→ 报错并给出修复建议。
+// 不在安装阶段联网下载，也不回退到其他平台的二进制。
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// 平台子包命名为「主包名-平台-架构」，主包改名（kit.config.json）时自动跟随。
+const BASE = require('../package.json').name;
+
+const SUPPORTED = new Set([
+  'darwin-arm64',
+  'darwin-x64',
+  'linux-x64',
+  'linux-arm64',
+  'win32-x64',
+  'win32-arm64',
+]);
+
+function platformKey(platform = process.platform, arch = process.arch) {
+  return `${platform}-${arch}`;
+}
+
+function binaryName(platform = process.platform) {
+  return platform === 'win32' ? 'zleap-app.exe' : 'zleap-app';
+}
+
+function platformPackage(platform = process.platform, arch = process.arch) {
+  return `${BASE}-${platformKey(platform, arch)}`;
+}
+
+class BinaryNotFoundError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'BinaryNotFoundError';
+  }
+}
+
+function resolveBinary(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const requireResolve = options.resolve || require.resolve;
+
+  const override = env.ZLEAP_APP_BINARY;
+  if (override) {
+    if (!fs.existsSync(override)) {
+      throw new BinaryNotFoundError(`ZLEAP_APP_BINARY 指向的文件不存在：${override}`);
+    }
+    return override;
+  }
+
+  const key = platformKey(platform, arch);
+  if (!SUPPORTED.has(key)) {
+    throw new BinaryNotFoundError(
+      `暂不提供 ${key} 平台的 zleap-app 预编译版本。` +
+        '可以从源码构建（go build ./cmd/zleap-app），再通过环境变量 ZLEAP_APP_BINARY 指定路径。',
+    );
+  }
+
+  const pkg = platformPackage(platform, arch);
+  let manifestPath;
+  try {
+    manifestPath = requireResolve(`${pkg}/package.json`);
+  } catch {
+    throw new BinaryNotFoundError(
+      `没有找到平台包 ${pkg}。\n` +
+        '常见原因：安装时使用了 --no-optional / --omit=optional，或在另一个平台上安装后拷贝了 node_modules。\n' +
+        `修复：重新安装依赖（不要省略 optionalDependencies），或执行 npm install ${pkg}。`,
+    );
+  }
+  const binary = path.join(path.dirname(manifestPath), 'bin', binaryName(platform));
+  if (!fs.existsSync(binary)) {
+    throw new BinaryNotFoundError(`平台包 ${pkg} 已安装，但缺少可执行文件：${binary}`);
+  }
+  return binary;
+}
+
+module.exports = { resolveBinary, platformKey, platformPackage, binaryName, BinaryNotFoundError, SUPPORTED };

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@zleap-ai/app-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.1",
+  "description": "zleapOS 云开发命令行工具 zleap-app（init / check / pack / publish / install / prepare / test / MCP），按平台自动选用预编译二进制",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RuoFeng2015/zleap-app-kit.git",
+    "directory": "packages/app-cli"
+  },
+  "type": "commonjs",
+  "bin": {
+    "zleap-app": "bin/zleap-app.js"
+  },
+  "main": "lib/resolve.js",
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@zleap-ai/app-cli-darwin-arm64": "0.10.1",
+    "@zleap-ai/app-cli-darwin-x64": "0.10.1",
+    "@zleap-ai/app-cli-linux-x64": "0.10.1",
+    "@zleap-ai/app-cli-linux-arm64": "0.10.1",
+    "@zleap-ai/app-cli-win32-x64": "0.10.1",
+    "@zleap-ai/app-cli-win32-arm64": "0.10.1"
+  },
+  "keywords": [
+    "zleap",
+    "zleapos",
+    "app-cloud",
+    "cli",
+    "mcp"
+  ]
+}