webpb 0.0.26 → 0.0.28

package/README.md

@@ -1,5 +1,10 @@
 # webpb
 
-The webpb runtime library
+TypeScript runtime and protoc code generation CLI for webpb.
+
+```shell
+npm install -D webpb
+npx webpb generate -o src/generated -I protos protos/*.proto
+```
 
 To view more, please visit: https://github.com/jinganix/webpb

package/cli/bin/webpb.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { runGenerate } from "../generate.js";
+export const HELP = `webpb — TypeScript runtime and protoc tooling for webpb
+
+Usage:
+  webpb generate [options] -- <files.proto...>
+
+Run "webpb generate --help" for generation options.
+`;
+export async function runCli(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === "-h" || command === "--help") {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (command === "generate") {
+        return runGenerate(rest);
+    }
+    console.error(`Unknown command: ${command}`);
+    process.stdout.write(HELP);
+    return 1;
+}
+function normalizeComparablePath(path) {
+    if (process.platform !== "win32") {
+        return path;
+    }
+    return path.replace(/^\\\\\?\\/, "").toLowerCase();
+}
+function resolveArgvEntryPath(argv) {
+    const entry = argv[1];
+    if (!entry) {
+        return "";
+    }
+    try {
+        return realpathSync(entry);
+    }
+    catch {
+        return entry;
+    }
+}
+function resolveModulePath(moduleUrl) {
+    try {
+        return realpathSync(fileURLToPath(moduleUrl));
+    }
+    catch {
+        return fileURLToPath(moduleUrl);
+    }
+}
+export function isMainModule(moduleUrl, argv = process.argv) {
+    const modulePath = normalizeComparablePath(resolveModulePath(moduleUrl));
+    const entryPath = normalizeComparablePath(resolveArgvEntryPath(argv));
+    return entryPath === modulePath;
+}
+export async function runMainEntrypoint(argv = process.argv, moduleUrl = import.meta.url) {
+    if (!isMainModule(moduleUrl, argv)) {
+        return undefined;
+    }
+    return runCli(argv.slice(2));
+}
+export async function bootstrapMain(argv = process.argv, moduleUrl = import.meta.url) {
+    if (!isMainModule(moduleUrl, argv)) {
+        return;
+    }
+    process.exit((await runMainEntrypoint(argv, moduleUrl)) ?? 0);
+}
+if (process.env.VITEST !== "true") {
+    await bootstrapMain();
+}

package/cli/generate.js

@@ -0,0 +1,58 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { bundledProtoInclude, packageRoot } from "./package-root.js";
+import { GENERATE_HELP, parseGenerateArgs } from "./parse-args.js";
+import { resolveProtocPlugin } from "./resolve-protoc-plugin.js";
+import { resolveProtoc } from "./resolve-protoc.js";
+function protocPath(filePath) {
+    return process.platform === "win32" ? filePath.replace(/\\/g, "/") : filePath;
+}
+export async function runGenerate(argv, rootOverride) {
+    const parsed = parseGenerateArgs(argv);
+    if (parsed.help) {
+        process.stdout.write(GENERATE_HELP);
+        return 0;
+    }
+    if (!parsed.out) {
+        console.error("Missing required option: --out");
+        process.stdout.write(GENERATE_HELP);
+        return 1;
+    }
+    if (parsed.protoFiles.length === 0) {
+        console.error("No .proto files specified");
+        process.stdout.write(GENERATE_HELP);
+        return 1;
+    }
+    for (const protoFile of parsed.protoFiles) {
+        if (!existsSync(protoFile)) {
+            console.error(`Proto file not found: ${protoFile}`);
+            return 1;
+        }
+    }
+    const root = rootOverride ?? packageRoot(import.meta.url);
+    const includeDirs = [...parsed.includes];
+    if (parsed.webpbProto) {
+        includeDirs.unshift(bundledProtoInclude(root));
+    }
+    mkdirSync(parsed.out, { recursive: true });
+    const protoc = await resolveProtoc(root, {
+        protobufVersion: parsed.protobufVersion,
+        protocPath: parsed.protoc,
+    });
+    const pluginBin = await resolveProtocPlugin(root, {
+        pluginPath: parsed.plugin,
+        webpbVersion: parsed.webpbVersion,
+    });
+    const args = [
+        ...includeDirs.flatMap((dir) => ["-I", protocPath(dir)]),
+        `--plugin=protoc-gen-ts=${protocPath(pluginBin)}`,
+        `--ts_out=${protocPath(parsed.out)}`,
+        ...parsed.protoFiles.map(protocPath),
+    ];
+    const result = spawnSync(protoc, args, { stdio: "inherit" });
+    if (result.error) {
+        console.error(`Failed to run ${protoc}. Install protoc, set PROTOC, or retry to auto-download.`);
+        return 1;
+    }
+    return result.status ?? 1;
+}

package/cli/package-root.js

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { executableExtension } from "./platform.js";
+export function packageRoot(moduleUrl) {
+    let dir = dirname(fileURLToPath(moduleUrl));
+    while (dir !== dirname(dir)) {
+        if (existsSync(join(dir, "package.json"))) {
+            return dir;
+        }
+        dir = dirname(dir);
+    }
+    throw new Error("webpb package root not found");
+}
+export function findMonorepoRoot(root) {
+    let dir = root;
+    while (dir !== dirname(dir)) {
+        if (existsSync(join(dir, "plugin", "go.mod"))) {
+            return dir;
+        }
+        dir = dirname(dir);
+    }
+    return undefined;
+}
+export function bundledProtoInclude(root) {
+    const packaged = join(root, "proto");
+    if (existsSync(packaged)) {
+        return packaged;
+    }
+    const monorepoRoot = findMonorepoRoot(root);
+    if (monorepoRoot) {
+        const monorepo = join(monorepoRoot, "lib/proto/src/main/resources");
+        if (existsSync(monorepo)) {
+            return monorepo;
+        }
+    }
+    throw new Error("webpb proto includes not found; reinstall the webpb npm package");
+}
+export function monorepoPluginPath(root) {
+    const monorepoRoot = findMonorepoRoot(root);
+    if (!monorepoRoot) {
+        return undefined;
+    }
+    const ext = executableExtension();
+    return join(monorepoRoot, "plugin/bin", `webpb-protoc-ts${ext}`);
+}
+export function readPackageVersion(root) {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    return pkg.version;
+}

package/cli/parse-args.js

@@ -0,0 +1,75 @@
+export const GENERATE_HELP = `Usage: webpb generate [options] -- <files.proto...>
+
+Generate TypeScript from protobuf definitions using the webpb protoc plugin.
+
+Options:
+  -o, --out <dir>              Output directory (--ts_out), required
+  -I, --include <dir>          Additional proto include path (repeatable)
+      --no-webpb-proto         Skip bundled webpb/WebpbExtend.proto includes
+      --protoc <path>          Path to protoc (default: PATH, then auto-download)
+      --plugin <path>          Path to webpb-protoc-ts (default: auto-download)
+      --webpb-version <ver>    webpb release version for plugin download
+      --protobuf-version <ver> protoc version for auto-download (default: bundled)
+  -h, --help                   Show this help
+
+Environment variables:
+  PROTOC                       Path to protoc
+  WEBPB_PROTOC_TS              Path to webpb-protoc-ts
+  WEBPB_VERSION                webpb release version for plugin download
+  WEBPB_PROTOBUF_VERSION       protoc version for auto-download
+
+Examples:
+  webpb generate -o src/generated -I protos protos/*.proto
+  webpb generate --out generated/proto --include ../proto src/*.proto
+`;
+export function parseGenerateArgs(argv) {
+    const result = {
+        includes: [],
+        protoFiles: [],
+        webpbProto: true,
+    };
+    let index = 0;
+    while (index < argv.length) {
+        const arg = argv[index];
+        if (arg === "--") {
+            result.protoFiles.push(...argv.slice(index + 1));
+            break;
+        }
+        switch (arg) {
+            case "-o":
+            case "--out":
+                result.out = argv[++index];
+                break;
+            case "-I":
+            case "--include":
+                result.includes.push(argv[++index]);
+                break;
+            case "--no-webpb-proto":
+                result.webpbProto = false;
+                break;
+            case "--protoc":
+                result.protoc = argv[++index];
+                break;
+            case "--plugin":
+                result.plugin = argv[++index];
+                break;
+            case "--webpb-version":
+                result.webpbVersion = argv[++index];
+                break;
+            case "--protobuf-version":
+                result.protobufVersion = argv[++index];
+                break;
+            case "-h":
+            case "--help":
+                return { help: true, includes: [], protoFiles: [], webpbProto: true };
+            default:
+                if (arg.startsWith("-")) {
+                    throw new Error(`Unknown option: ${arg}`);
+                }
+                result.protoFiles.push(arg);
+                break;
+        }
+        index += 1;
+    }
+    return result;
+}

package/cli/platform.js

@@ -0,0 +1,39 @@
+export function webpbReleasePlatform(platform = process.platform, arch = process.arch) {
+    if (platform === "darwin") {
+        return arch === "arm64" ? "darwin-arm64" : "darwin-amd64";
+    }
+    if (platform === "linux") {
+        return arch === "arm64" ? "linux-arm64" : "linux-amd64";
+    }
+    if (platform === "win32") {
+        return arch === "ia32" ? "windows-386" : "windows-amd64";
+    }
+    throw new Error(`Unsupported platform: ${platform} ${arch}`);
+}
+export function protocMavenClassifier(platform = process.platform, arch = process.arch) {
+    if (platform === "darwin") {
+        return arch === "arm64" ? "osx-aarch_64" : "osx-x86_64";
+    }
+    if (platform === "linux") {
+        if (arch === "arm64") {
+            return "linux-aarch_64";
+        }
+        if (arch === "ppc64") {
+            return "linux-ppcle_64";
+        }
+        if (arch === "s390x") {
+            return "linux-s390_64";
+        }
+        if (arch === "ia32") {
+            return "linux-x86_32";
+        }
+        return "linux-x86_64";
+    }
+    if (platform === "win32") {
+        return arch === "ia32" ? "windows-x86_32" : "windows-x86_64";
+    }
+    throw new Error(`Unsupported platform: ${platform} ${arch}`);
+}
+export function executableExtension(platform = process.platform) {
+    return platform === "win32" ? ".exe" : "";
+}

package/cli/resolve-protoc-plugin.js

@@ -0,0 +1,114 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, createWriteStream, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { monorepoPluginPath, readPackageVersion } from "./package-root.js";
+import { executableExtension, webpbReleasePlatform } from "./platform.js";
+const defaultExit = (code) => {
+    process.exit(code);
+};
+function defaultWebpbVersion(root, versionOverride) {
+    if (process.env.WEBPB_VERSION) {
+        return process.env.WEBPB_VERSION;
+    }
+    if (versionOverride) {
+        return versionOverride;
+    }
+    return readPackageVersion(root);
+}
+export function cachePluginPath(version) {
+    const ext = executableExtension();
+    return join(homedir(), ".cache", "webpb", version, `webpb-protoc-ts-${webpbReleasePlatform()}${ext}`);
+}
+export async function downloadReleaseBinary(version, destination, platform = process.platform) {
+    const ext = executableExtension(platform);
+    const releasePlatform = webpbReleasePlatform(platform);
+    const assetName = `webpb-protoc-ts-${releasePlatform}${ext}`;
+    const url = `https://github.com/jinganix/webpb/releases/download/v${version}/${assetName}`;
+    mkdirSync(dirname(destination), { recursive: true });
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download ${url}: HTTP ${response.status}`);
+    }
+    if (!response.body) {
+        throw new Error(`Failed to download ${url}: empty response body`);
+    }
+    await pipeline(response.body, createWriteStream(destination));
+    if (platform !== "win32") {
+        chmodSync(destination, 0o755);
+    }
+}
+export function findPluginDir(root) {
+    let dir = root;
+    while (dir !== dirname(dir)) {
+        if (existsSync(join(dir, "plugin", "go.mod"))) {
+            return join(dir, "plugin");
+        }
+        dir = dirname(dir);
+    }
+    return undefined;
+}
+export function buildFromSource(root, exit) {
+    const ext = executableExtension();
+    const binaryName = `webpb-protoc-ts${ext}`;
+    const pluginDir = findPluginDir(root);
+    if (!pluginDir) {
+        return;
+    }
+    console.log("Building webpb-protoc-ts from source...");
+    const result = spawnSync("go", ["build", "-o", join("bin", binaryName), "./cmd/webpb-ts"], { cwd: pluginDir, stdio: "inherit" });
+    if (result.status !== 0) {
+        exit(result.status ?? 1);
+    }
+}
+export function resolvePluginAfterFailedDownload(root, exit) {
+    if (findPluginDir(root)) {
+        buildFromSource(root, exit);
+        const rebuiltPath = monorepoPluginPath(root);
+        if (rebuiltPath && existsSync(rebuiltPath)) {
+            return rebuiltPath;
+        }
+    }
+    return undefined;
+}
+export async function resolveProtocPlugin(root, options = {}) {
+    const exit = options.exit ?? defaultExit;
+    if (options.pluginPath) {
+        return options.pluginPath;
+    }
+    if (process.env.WEBPB_PROTOC_TS) {
+        return process.env.WEBPB_PROTOC_TS;
+    }
+    const localPath = monorepoPluginPath(root);
+    if (localPath && existsSync(localPath)) {
+        return localPath;
+    }
+    const version = defaultWebpbVersion(root, options.webpbVersion);
+    const cachedPath = cachePluginPath(version);
+    if (existsSync(cachedPath)) {
+        return cachedPath;
+    }
+    try {
+        console.log(`Downloading webpb-protoc-ts ${version} for ${webpbReleasePlatform()}...`);
+        await downloadReleaseBinary(version, cachedPath);
+        return cachedPath;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`Release download failed: ${message}`);
+    }
+    const rebuilt = resolvePluginAfterFailedDownload(root, exit);
+    if (rebuilt) {
+        return rebuilt;
+    }
+    console.error([
+        "webpb-protoc-ts not found.",
+        "Install options:",
+        "  - set WEBPB_PROTOC_TS to the plugin binary path",
+        "  - download from https://github.com/jinganix/webpb/releases",
+        "  - set WEBPB_VERSION and retry (auto-download)",
+        "  - build from source: cd plugin && make build",
+    ].join("\n"));
+    return exit(1);
+}

package/cli/resolve-protoc.js

@@ -0,0 +1,81 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, createWriteStream, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { executableExtension, protocMavenClassifier } from "./platform.js";
+import { readBundledVersions } from "./versions.js";
+const defaultExit = (code) => {
+    process.exit(code);
+};
+export function cacheProtocPath(protobufVersion) {
+    const ext = executableExtension();
+    return join(homedir(), ".cache", "webpb", "protoc", protobufVersion, `protoc${ext}`);
+}
+export function resolveOnPath(command) {
+    if (!command) {
+        return undefined;
+    }
+    const lookup = process.platform === "win32" ? "where" : "which";
+    const result = spawnSync(lookup, [command], { encoding: "utf8" });
+    if (result.status !== 0) {
+        return undefined;
+    }
+    const resolved = result.stdout.trim().split(/\r?\n/)[0];
+    return resolved || undefined;
+}
+export async function downloadProtocFromMaven(protobufVersion, destination, platform = process.platform) {
+    const classifier = protocMavenClassifier();
+    const fileName = `protoc-${protobufVersion}-${classifier}.exe`;
+    const url = `https://repo1.maven.org/maven2/com/google/protobuf/protoc/${protobufVersion}/${fileName}`;
+    mkdirSync(dirname(destination), { recursive: true });
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download ${url}: HTTP ${response.status}`);
+    }
+    if (!response.body) {
+        throw new Error(`Failed to download ${url}: empty response body`);
+    }
+    await pipeline(response.body, createWriteStream(destination));
+    if (platform !== "win32") {
+        chmodSync(destination, 0o755);
+    }
+}
+export async function resolveProtoc(root, options = {}) {
+    const exit = options.exit ?? defaultExit;
+    if (options.protocPath) {
+        return options.protocPath;
+    }
+    if (process.env.PROTOC) {
+        return process.env.PROTOC;
+    }
+    const onPath = resolveOnPath("protoc");
+    if (onPath) {
+        return onPath;
+    }
+    const bundled = readBundledVersions(root);
+    const protobufVersion = options.protobufVersion ??
+        process.env.WEBPB_PROTOBUF_VERSION ??
+        bundled.protobufVersion;
+    const cachedPath = cacheProtocPath(protobufVersion);
+    if (existsSync(cachedPath)) {
+        return cachedPath;
+    }
+    try {
+        console.log(`Downloading protoc ${protobufVersion} for ${protocMavenClassifier()}...`);
+        await downloadProtocFromMaven(protobufVersion, cachedPath);
+        return cachedPath;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to download protoc: ${message}`);
+        console.error([
+            "protoc not found.",
+            "Install options:",
+            "  - add protoc to PATH",
+            "  - set PROTOC to the protoc binary path",
+            "  - set WEBPB_PROTOBUF_VERSION and retry (auto-download from Maven Central)",
+        ].join("\n"));
+        return exit(1);
+    }
+}

package/cli/versions.js

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+export function readBundledVersions(root) {
+    const path = join(root, "webpb-version.properties");
+    const text = readFileSync(path, "utf8");
+    const props = Object.fromEntries(text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith("#"))
+        .map((line) => {
+        const separator = line.indexOf("=");
+        return [line.slice(0, separator), line.slice(separator + 1)];
+    }));
+    if (!props.webpbVersion || !props.protobufVersion) {
+        throw new Error(`Invalid webpb-version.properties at ${path}`);
+    }
+    return {
+        protobufVersion: props.protobufVersion,
+        webpbVersion: props.webpbVersion,
+    };
+}

package/package.json

@@ -1,62 +1,40 @@
 {
-  "name": "webpb",
-  "version": "0.0.26",
-  "description": "The webpb runtime library",
-  "scripts": {
-    "build": "rimraf build/**/* && tsc && vite build && dts-bundle-generator --config ./dts-bundle-generator.config.cjs && copyfiles ./README.md ./package.json build",
-    "check": "npm run lint && npm run test",
-    "lint": "eslint --quiet src/**/*.ts",
-    "lint:fix": "eslint --fix src/**/*.ts",
-    "deploy": "npm run check && npm run build && npm publish ./build --access public",
-    "publish": "npm run sync-version && npm run build && npm publish ./build --access public",
-    "sync-version": "node scripts/sync-version.mjs",
-    "test": "vitest --coverage"
-  },
   "author": "jinganix@gmail.com",
-  "license": "Apache-2.0",
+  "bin": {
+    "webpb": "./cli/bin/webpb.js"
+  },
+  "description": "webpb TypeScript runtime and protoc code generation CLI",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./proto": "./proto"
+  },
+  "files": [
+    "cli",
+    "dist",
+    "proto",
+    "webpb-version.properties",
+    "README.md"
+  ],
   "keywords": [
     "webpb",
+    "protobuf",
+    "protoc",
     "runtime"
   ],
+  "license": "Apache-2.0",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "name": "webpb",
   "repository": {
     "type": "git",
     "url": "https://github.com/jinganix/webpb"
   },
-  "type": "module",
   "sideEffects": false,
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.mjs",
+  "type": "module",
   "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^25.9.3",
-    "@typescript-eslint/eslint-plugin": "^8.59.4",
-    "@typescript-eslint/parser": "^8.59.4",
-    "@vitest/coverage-v8": "^4.1.7",
-    "copyfiles": "^2.4.1",
-    "dts-bundle-generator": "^9.5.1",
-    "eslint": "^10.4.1",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-import-quotes": "^0.0.1",
-    "eslint-plugin-import-x": "^4.16.2",
-    "eslint-plugin-no-null": "^1.0.2",
-    "eslint-plugin-perfectionist": "^4.15.0",
-    "eslint-plugin-prettier": "^5.5.5",
-    "globals": "^14.0.0",
-    "prettier": "^3.8.4",
-    "pretty-quick": "^4.2.2",
-    "rimraf": "^6.1.3",
-    "ts-node": "^10.9.2",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.4",
-    "vite": "^8.0.14",
-    "vitest": "^4.1.7"
-  }
+  "version": "0.0.28"
 }