@eiva/protoc-gen-fletcher 0.1.1-alpha

package/README.md

@@ -0,0 +1,86 @@
+# @eiva/protoc-gen-fletcher
+
+[![npm (scoped)](https://img.shields.io/npm/v/@eiva/protoc-gen-fletcher?label=latest)](https://www.npmjs.com/package/@eiva/protoc-gen-fletcher)
+
+A `protoc` plugin that generates typed `TypedSchema<T>` modules (`.fletcher.ts`) from `.proto` files. Pairs with [`@eiva/fletcher-gateway-client`](https://www.npmjs.com/package/@eiva/fletcher-gateway-client), Fletcher's WebSocket gateway runtime.
+
+This package is a thin Node.js shim. On first invocation it downloads the platform-matching native plugin binary from [Fletcher's GitHub Releases](https://github.com/eivacom/Fletcher/releases) and caches it under `~/.cache/protoc-gen-fletcher/<version>/`. Subsequent invocations exec the cached binary directly.
+
+## Installation
+
+```bash
+npm install --save-dev @eiva/protoc-gen-fletcher
+```
+
+```bash
+npm install --save-dev @protobuf-ts/protoc
+```
+
+```bash
+npm install --save-dev fletcher-gateway-client@npm:@eiva/fletcher-gateway-client
+```
+
+Three pieces:
+
+- **`@eiva/protoc-gen-fletcher`** — this plugin shim.
+- **`@protobuf-ts/protoc`** — ships the `protoc` compiler binary itself. Declared as a peer dependency; npm 7+ auto-installs it, older npm versions print a warning. Install explicitly above to be safe.
+- **`fletcher-gateway-client`** under the bare alias `npm:@eiva/fletcher-gateway-client` — the generated `.fletcher.ts` files import `WireTypeId` and the `TypedSchema` type from a **bare** `'fletcher-gateway-client'` specifier. Installing under that alias makes the published `@eiva/fletcher-gateway-client` resolve at runtime via standard Node resolution (no tsconfig path-alias trickery needed).
+
+## Usage
+
+Wire `proto:gen` into your `package.json`. Adding it as a `prebuild` script keeps generated bindings in sync with `.proto` changes automatically — every `npm run build` regenerates first.
+
+```json
+{
+  "scripts": {
+    "proto:gen": "node -e \"require('fs').mkdirSync('src/generated',{recursive:true})\" && protoc --fletcher_opt=ts --fletcher_out=src/generated -I proto proto/*.proto",
+    "prebuild": "npm run proto:gen",
+    "build": "tsc"
+  }
+}
+```
+
+Two notes:
+
+- The leading `node -e mkdirSync(...)` ensures `src/generated/` exists before `protoc` runs — `protoc` does not auto-create its `--fletcher_out` directory, and `mkdir -p` is not portable to Windows.
+- No `--plugin=` flag is needed. `protoc` searches `PATH` (which npm prepends `node_modules/.bin/` to during script execution) for `protoc-gen-<name>` based on the `--<name>_out` flag, with the OS's executable-extension rules — so the `protoc-gen-fletcher.cmd` wrapper that npm writes alongside the bin shim is found correctly on Windows.
+
+Then:
+
+```bash
+npm run build
+```
+
+…regenerates `src/generated/*.fletcher.ts` and compiles. Consume the generated descriptor:
+
+```ts
+import { FletcherClient } from '@eiva/fletcher-gateway-client';
+import { Telemetry, type ITelemetry } from './generated/telemetry.fletcher.js';
+
+const client = new FletcherClient({ url: 'ws://localhost:9090' });
+await client.connect();
+
+await client.publish('telemetry', Telemetry, {
+  sensor_id: 42,
+  temperature: 23.5,
+} satisfies ITelemetry);
+```
+
+## Supported platforms
+
+| OS / arch | GitHub Release asset |
+|---|---|
+| `linux/x64` | `protoc-gen-fletcher-linux-x64` |
+| `win32/x64` | `protoc-gen-fletcher-windows-x64.exe` |
+
+Adding macOS / arm64 is tracked in [Fletcher's issue tracker](https://github.com/eivacom/Fletcher/issues).
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `PROTOC_GEN_FLETCHER_RELEASES_URL` | Override the GitHub Releases base URL (e.g. to test against a fork or a mirror). Default: `https://github.com/eivacom/Fletcher/releases/download`. |
+
+## License
+
+LGPL-3.0-or-later © The Fletcher Authors. The shim itself is in this repo at [`protoc/npm/`](https://github.com/eivacom/Fletcher/tree/main/protoc/npm); the native plugin source is in [`protoc/`](https://github.com/eivacom/Fletcher/tree/main/protoc).

package/bin/protoc-gen-fletcher.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: LGPL-3.0-or-later
+// Copyright (C) 2026 The Fletcher Authors
+//
+// Node.js shim for the fletcher-protoc plugin. On first invocation it
+// downloads the platform-matching native binary from this package's matching
+// protoc-v<version> GitHub Release, caches it under
+// ~/.cache/protoc-gen-fletcher/<version>/, and exec's it with inherited
+// stdin/stdout/stderr so protoc's CodeGeneratorRequest / CodeGeneratorResponse
+// pipe protocol passes through the shim unchanged.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const https = require('node:https');
+const { spawnSync } = require('node:child_process');
+
+const { version: VERSION } = require('../package.json');
+const RELEASE_BASE =
+  process.env.PROTOC_GEN_FLETCHER_RELEASES_URL ||
+  'https://github.com/eivacom/Fletcher/releases/download';
+
+function platformAssetName() {
+  const platform = os.platform();
+  const arch = os.arch();
+  if (platform === 'linux' && arch === 'x64') {
+    return 'protoc-gen-fletcher-linux-x64';
+  }
+  if (platform === 'win32' && arch === 'x64') {
+    return 'protoc-gen-fletcher-windows-x64.exe';
+  }
+  throw new Error(
+    `protoc-gen-fletcher: unsupported platform ${platform}/${arch}. ` +
+      `Supported: linux/x64, win32/x64.`,
+  );
+}
+
+function cacheDir() {
+  return path.join(os.homedir(), '.cache', 'protoc-gen-fletcher', VERSION);
+}
+
+function followRedirects(url, depth) {
+  if (depth > 5) {
+    return Promise.reject(new Error(`Too many redirects: ${url}`));
+  }
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume();
+          return resolve(followRedirects(res.headers.location, depth + 1));
+        }
+        if (res.statusCode !== 200) {
+          return reject(
+            new Error(
+              `Download failed (${res.statusCode}): ${url}\n` +
+                `Check that the release exists at ` +
+                `https://github.com/eivacom/Fletcher/releases/tag/protoc-v${VERSION}`,
+            ),
+          );
+        }
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+        res.on('error', reject);
+      })
+      .on('error', reject);
+  });
+}
+
+async function ensureBinary() {
+  const asset = platformAssetName();
+  const cacheBin = path.join(cacheDir(), asset);
+  if (fs.existsSync(cacheBin)) {
+    return cacheBin;
+  }
+
+  const url = `${RELEASE_BASE}/protoc-v${VERSION}/${asset}`;
+  process.stderr.write(`protoc-gen-fletcher: downloading ${url}\n`);
+
+  fs.mkdirSync(cacheDir(), { recursive: true });
+  const buf = await followRedirects(url, 0);
+
+  // Atomic write: write to a unique tmp file in the same dir, then rename.
+  // Multiple npm scripts may invoke the shim in parallel; rename within the
+  // same filesystem is atomic so concurrent callers cannot see a half-written
+  // file.
+  const tmp = `${cacheBin}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, buf, { mode: 0o755 });
+  fs.renameSync(tmp, cacheBin);
+
+  return cacheBin;
+}
+
+(async () => {
+  try {
+    const binary = await ensureBinary();
+    // stdio: 'inherit' makes the child binary share this Node process's
+    // stdin/stdout/stderr handles. protoc spawns us with pipe-based
+    // stdin/stdout for the plugin protocol; the binary inherits those exact
+    // pipes and reads/writes them directly. Node never touches the bytes.
+    const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+    process.exit(result.status === null ? 1 : result.status);
+  } catch (err) {
+    process.stderr.write(`protoc-gen-fletcher: ${err.message}\n`);
+    process.exit(1);
+  }
+})();

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@eiva/protoc-gen-fletcher",
+  "version": "0.1.1-alpha",
+  "description": "protoc plugin that generates typed TypeScript schema descriptors for Fletcher's positional wire format. Downloads the platform-matching native plugin binary from GitHub Releases on first invocation.",
+  "license": "LGPL-3.0-or-later",
+  "homepage": "https://github.com/eivacom/Fletcher/tree/main/protoc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eivacom/Fletcher.git",
+    "directory": "protoc/npm"
+  },
+  "bugs": {
+    "url": "https://github.com/eivacom/Fletcher/issues"
+  },
+  "keywords": [
+    "protoc",
+    "protobuf",
+    "fletcher",
+    "code-generation",
+    "typescript"
+  ],
+  "bin": {
+    "protoc-gen-fletcher": "./bin/protoc-gen-fletcher.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@protobuf-ts/protoc": "^2.9.5"
+  }
+}