@servelink/serve 0.7.0

package/README.md

@@ -0,0 +1,32 @@
+# @servelink/serve
+
+Public tunnel for hosted serve accounts. This package is a thin wrapper: on
+install (postinstall) it downloads the native `serve` CLI binary for your
+platform from the public [servelink-swyftlabs/serve-dist](https://github.com/servelink-swyftlabs/serve-dist)
+releases, verifies its sha256 against `checksums.txt`, and extracts it. The
+binary that runs is exactly the CI-published GoReleaser artifact — no Go code
+is compiled here.
+
+## Install
+
+```sh
+npm i -g @servelink/serve
+# or, without a global install:
+npx @servelink/serve
+```
+
+## Use
+
+```sh
+serve login    # authorize this device (prints a dashboard URL + code)
+serve          # run the MCP server for AI coding agents
+serve mcp      # explicit MCP form
+```
+
+The primary interface is **MCP**: with a bare `serve` registered in your AI
+coding agent, the agent can "serve me this" — a file, a directory, or an
+already-running dev server — and hand back a public HTTPS URL.
+
+See the README at the repository root for full onboarding. If your platform is
+unsupported by npm, install via the [Homebrew tap](https://github.com/servelink-swyftlabs/homebrew-tap)
+or a release archive from serve-dist.

package/bin/serve.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+"use strict";
+
+// @servelink/serve — CLI entrypoint. Finds the native binary installed by
+// install.js and spawns it, forwarding args and inheriting stdio so `serve <port>`
+// and `serve login` behave exactly like the Go CLI.
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const nativeDir = path.join(__dirname, "..", "native");
+const binName = process.platform === "win32" ? "serve.exe" : "serve";
+const binPath = path.join(nativeDir, binName);
+
+if (!fs.existsSync(binPath)) {
+  console.error(
+    "serve: native binary not found (expected " + binPath + ").\n" +
+      "Reinstall it with: npm rebuild @servelink/serve"
+  );
+  process.exit(1);
+}
+
+const res = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+if (res.error) {
+  console.error("serve: failed to launch native binary: " + res.error.message);
+  process.exit(1);
+}
+process.exit(res.status === null ? 1 : res.status);

package/install.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+"use strict";
+
+// @servelink/serve — postinstall.
+// Downloads the matching-platform `serve` client binary from the public
+// servelink-swyftlabs/serve-dist releases repo, verifies it against checksums.txt, and
+// extracts it into ./native so bin/serve.js can invoke it. The binary that runs
+// is exactly the GoReleaser artifact — this package contains no Go code.
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const https = require("node:https");
+const path = require("node:path");
+const zlib = require("node:zlib");
+
+const REPO = "servelink-swyftlabs/serve-dist";
+const DIST = "https://github.com/" + REPO + "/releases/download";
+
+function resolveVersion() {
+  const pkg = require("./package.json");
+  const v = pkg.version;
+  if (!v || v === "0.0.0") {
+    throw new Error(
+      "@servelink/serve: package version must be set before publish. " +
+        "CI publishes with the GoReleaser tag as the npm version (see release.yml)."
+    );
+  }
+  return v;
+}
+
+// Nothing is ever silently skipped: an unsupported platform fails loudly and
+// points at the manual install paths.
+function resolvePlatform() {
+  const osMap = { darwin: "darwin", linux: "linux", win32: "windows" };
+  const archMap = { x64: "amd64", arm64: "arm64" };
+  const os = osMap[process.platform];
+  const arch = archMap[process.arch];
+  if (!os || !arch) {
+    throw new Error(
+      "@servelink/serve: unsupported platform " + process.platform + "/" + process.arch + ". " +
+        "Install via the Homebrew tap or the release archive from " +
+        "https://github.com/" + REPO + "/releases"
+    );
+  }
+  // GoReleaser serves client archives for darwin/linux (amd64+arm64) and
+  // windows/amd64. Anything else has no published artifact.
+  if (os === "windows" && arch !== "amd64") {
+    throw new Error(
+      "@servelink/serve: no published binary for windows/" + arch + ". " +
+        "Install via the release archive from https://github.com/" + REPO + "/releases"
+    );
+  }
+  return { os, arch };
+}
+
+// Parses a GoReleaser checksums.txt (one "<sha256>  <filename>" per line) and
+// returns the expected sha256 hex for filename, or null if absent.
+function checksumFor(filename, checksumsText) {
+  for (const raw of checksumsText.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    const m = /^([0-9a-fA-F]{64})\s+(\S+)\s*$/.exec(line);
+    if (m && m[2] === filename) return m[1].toLowerCase();
+  }
+  return null;
+}
+
+function verifySha256(data, expectedHex) {
+  return crypto.createHash("sha256").update(data).digest("hex") === expectedHex;
+}
+
+function download(url, redirects) {
+  redirects = redirects || 0;
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { headers: { "User-Agent": "@servelink/serve-installer" } }, (res) => {
+      const status = res.statusCode;
+      if (status >= 300 && status < 400 && res.headers.location && redirects < 5) {
+        res.resume();
+        download(new URL(res.headers.location, url).toString(), redirects + 1).then(resolve, reject);
+        return;
+      }
+      if (status !== 200) {
+        res.resume();
+        reject(new Error("HTTP " + status + " while downloading " + url));
+        return;
+      }
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => resolve(Buffer.concat(chunks)));
+      res.on("error", reject);
+    });
+    req.on("error", reject);
+  });
+}
+
+// Minimal ustar tar reader over an already-gunzipped buffer. Only regular-file
+// entries are kept. GoReleaser archives use short top-level names (serve,
+// LICENSE, README.md), so PAX/GNU long-name extensions are not needed.
+function readTarFiles(buf) {
+  const files = new Map();
+  let offset = 0;
+  const readStr = (o, len) => {
+    let end = o;
+    while (end < o + len && buf[end] !== 0) end++;
+    return buf.toString("utf8", o, end);
+  };
+  while (offset + 512 <= buf.length) {
+    const base = offset; // absolute offset of the current 512-byte header
+    const name = readStr(base, 100);
+    if (name.length === 0) break; // end-of-archive marker (zero block)
+    const size = parseInt(readStr(base + 124, 12).trim(), 8) || 0;
+    const typeflag = String.fromCharCode(buf[base + 156]);
+    const dataStart = base + 512;
+    offset = dataStart + Math.ceil(size / 512) * 512;
+    if (typeflag === "0" || typeflag === "" || typeflag === "\u0000") {
+      files.set(name, buf.subarray(dataStart, dataStart + size));
+    }
+    // Directories, symlinks, PAX headers, etc. are intentionally ignored.
+  }
+  return files;
+}
+
+async function run() {
+  const version = resolveVersion();
+  const { os, arch } = resolvePlatform();
+
+  const archiveName = "serve_" + version + "_" + os + "_" + arch + ".tar.gz";
+  const distDir = path.join(__dirname, "native");
+  fs.mkdirSync(distDir, { recursive: true });
+
+  // The GitHub release tag on serve-dist is `v<version>` (e.g. v0.4.0), while
+  // the GoReleaser archive filename uses {{ .Version }} (the tag with the leading
+  // "v" stripped, e.g. serve_0.4.0_darwin_amd64.tar.gz). The npm package version
+  // is set to the stripped tag, so the archive name matches directly, but the
+  // download URL must re-add the "v" prefix to hit the actual release tag.
+  const releaseTag = "v" + version;
+  const archiveUrl = DIST + "/" + releaseTag + "/" + archiveName;
+  const checksumsUrl = DIST + "/" + releaseTag + "/checksums.txt";
+
+  const [archive, checksumsText] = await Promise.all([
+    download(archiveUrl),
+    download(checksumsUrl).then((b) => b.toString("utf8")),
+  ]);
+
+  const expected = checksumFor(archiveName, checksumsText);
+  if (!expected) {
+    throw new Error("@servelink/serve: " + archiveName + " missing from checksums.txt; cannot verify integrity.");
+  }
+  if (!verifySha256(archive, expected)) {
+    throw new Error(
+      "@servelink/serve: checksum mismatch for " + archiveName +
+        ". Refusing to install an unverified binary."
+    );
+  }
+
+  const files = readTarFiles(zlib.gunzipSync(archive));
+  const entry = files.get("serve");
+  if (!entry) {
+    throw new Error("@servelink/serve: 'serve' not found in " + archiveName);
+  }
+
+  const binPath = path.join(distDir, "serve");
+  fs.writeFileSync(binPath, entry);
+  fs.chmodSync(binPath, 0o755);
+
+  const { spawnSync } = require("node:child_process");
+  const probe = spawnSync(binPath, ["--version"], { encoding: "utf8" });
+  if (probe.status !== 0) {
+    throw new Error(
+      "@servelink/serve: installed binary failed --version check: " +
+        (probe.stderr || probe.stdout || "exit " + probe.status)
+    );
+  }
+  console.log("@servelink/serve: installed serve " + probe.stdout.trim() + " (" + os + "/" + arch + ")");
+}
+
+if (require.main === module) {
+  run().catch((err) => {
+    console.error(err && err.message ? err.message : String(err));
+    process.exit(1);
+  });
+}
+
+module.exports = { resolvePlatform, checksumFor, verifySha256, readTarFiles };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@servelink/serve",
+  "version": "0.7.0",
+  "description": "Public tunnel for hosted serve accounts. Thin wrapper that downloads and invokes the native serve CLI.",
+  "bin": {
+    "serve": "bin/serve.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js",
+    "test": "node --test test/install.test.js"
+  },
+  "files": [
+    "bin/",
+    "install.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "license": "Proprietary",
+  "keywords": [
+    "tunnel",
+    "ngrok",
+    "localhost",
+    "reverse-tunnel",
+    "mcp",
+    "cli"
+  ]
+}