webpb 0.0.25 → 0.0.27

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/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function s(e,r,o=[]){if(!(!e||!r||typeof e!="object"||typeof r!="object"))for(const[i,n]of Object.entries(e))n!==void 0&&o.indexOf(i)<0&&(r[i]=n)}function c(e,r){if(e==null||typeof e!="object")return null;for(const o of r.split("."))if(e=e[o],e==null)return null;return e}function l(e,r){const o=[],i=(n,t)=>{n&&t&&o.push(`${n}=${encodeURIComponent(t)}`)};for(const[n,t]of Object.entries(r))if(!(t==null||typeof t=="function"))if(Array.isArray(t))i(n,t.join(","));else if(typeof t=="object")for(const u of Object.keys(t)){const f=t[u];u&&i(n,f?u+","+f:u)}else i(n,String(t));return o.length?`${e}${o.join("&")}`:""}function y(e,r){if(!e||typeof e!="object"||Array.isArray(e))return e;const o={};for(const[i,n]of Object.entries(e)){const t=n?.toAlias;typeof t=="function"?o[i]=t():r&&r[i]?o[r[i]]=n:o[i]=n}return o}function p(e,r){return Object.entries(e).reduce((o,[i,n])=>(o[i]=r(n),o),{})}exports.assign=s;exports.getter=c;exports.mapValues=p;exports.query=l;exports.toAlias=y;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);return t===null||t===Object.prototype}function t(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function n(e){if(!t(e))return;let n=e;if(typeof n.toAlias==`function`)return n.toAlias.bind(e);if(typeof n.toWebpbAlias==`function`)return n.toWebpbAlias.bind(e)}function r(e){return n(e)!==void 0}function i(e){let t=n(e);return t?t():e}function a(n,r,i=[]){if(!e(n)||!t(r))return;let a=new Set(i);for(let[e,t]of Object.entries(n))t!==void 0&&!a.has(e)&&(r[e]=t)}function o(e,n){if(e==null)return null;let r=n.split(`.`).filter(e=>e.length>0);if(r.length===0)return e;let i=e;for(let e of r)if(!t(i)||(i=i[e],i==null))return null;return i}function s(t,n){let r=[],i=(e,t)=>{e&&t&&r.push(`${e}=${encodeURIComponent(t)}`)};for(let[t,r]of Object.entries(n))if(!(r==null||typeof r==`function`)){if(Array.isArray(r)){r.length>0&&i(t,r.join(`,`));continue}if(e(r)){for(let e of Object.keys(r)){let n=r[e];n==null||n===``?e&&i(t,e):e&&i(t,`${e},${n}`)}continue}i(t,String(r))}return r.length?`${t}${r.join(`&`)}`:``}function c(t,n){if(!e(t))return t;let a={};for(let[e,o]of Object.entries(t))r(o)?a[e]=i(o):n[e]?a[n[e]]=o:a[e]=o;return a}function l(t,n){return e(t)?Object.entries(t).reduce((e,[t,r])=>(e[t]=n(r),e),{}):{}}exports.assign=a,exports.getter=o,exports.mapValues=l,exports.query=s,exports.toAlias=c;

package/dist/index.d.ts

@@ -2,7 +2,7 @@
 
 export type Constructor<T> = {
 	new (): T;
-	fromAlias<T, D>(this: Constructor<T>, data: Partial<D>): T;
+	fromAlias(data?: unknown): T;
 };
 export type AnyObject = Record<string | number, unknown>;
 export interface WebpbMessage {
@@ -15,7 +15,7 @@ export interface WebpbMeta {
 	context: string;
 	path: string;
 }
-export declare function assign(src: unknown, dest: unknown, excludes?: string[]): void;
+export declare function assign(src: unknown, dest: unknown, excludes?: readonly string[]): void;
 export declare function getter(data: unknown, path: string): unknown;
 export declare function query(pre: string, params: {
 	[key: string]: unknown;
@@ -23,6 +23,6 @@ export declare function query(pre: string, params: {
 export declare function toAlias(data: unknown, aliases: {
 	[key: string]: string;
 }): unknown;
-export declare function mapValues(record: AnyObject, mapping: (v: unknown) => unknown): AnyObject;
+export declare function mapValues(record: AnyObject | null | undefined, mapping: (v: unknown) => unknown): AnyObject;
 
 export {};