@itsbjoern/roost 0.1.4 → 0.1.8

package/README.md

@@ -1,19 +1,34 @@
 ## @itsbjoern/roost
 
-This is the npm wrapper for the Roost CLI.
-
-It downloads a prebuilt `roost` binary from the GitHub Releases of `itsbjoern/roost`
-for your platform and exposes it as the `roost` command.
+This is the npm wrapper for the Roost CLI. It downloads a prebuilt `roost` binary from GitHub Releases and exposes the `roost` command. You can also use the **JavaScript API** from Node without shelling out.
 
 ### Install
 
 ```bash
+# Global install — use `roost` from anywhere:
 npm install -g @itsbjoern/roost
+
+# Local install — use via npx:
+npm install @itsbjoern/roost
 ```
 
-Then:
+Then (CLI):
 
 ```bash
-roost init
+roost init          # after global install
+npx roost init      # after local install
+```
+
+### JavaScript API
+
+Use the package as a library to get cert/key **contents** (or paths) for HTTPS config. Use `getDomainCerts` for build tools—returns literal PEM strings, no file reads:
+
+```js
+const { getDomainCerts } = require('@itsbjoern/roost');
+
+const { cert, key } = await getDomainCerts('api.local', { generate: true });
+// Pass cert and key directly to https.createServer or Vite server.https
 ```
 
+See the [main README](https://github.com/itsbjoern/roost#javascript-api) for full API docs and examples.
+

package/index.d.ts

@@ -0,0 +1,58 @@
+import { type ExecFileOptions } from "child_process";
+/**
+ * Options for execFile when running the roost binary.
+ */
+export interface RunRoostOptions extends ExecFileOptions {
+}
+/**
+ * Options for domain path helpers. Can be combined with exec options.
+ * - generate: if true, run `domain add` when the domain doesn't exist
+ * - exact: when generating, create cert for exact domain only (no wildcard)
+ * - allow: when generating, allow any TLD (bypass allowlist)
+ */
+export interface DomainPathOptions extends RunRoostOptions {
+    generate?: boolean;
+    exact?: boolean;
+    allow?: boolean;
+}
+/**
+ * Resolved filesystem paths for a domain's certificate and private key.
+ * Returned by {@link getDomainPaths}.
+ */
+export interface DomainPaths {
+    cert: string;
+    key: string;
+}
+/**
+ * Literal certificate and private key contents (PEM strings).
+ * Returned by {@link getDomainCerts} for direct use with HTTPS config—no file reads needed.
+ */
+export interface DomainCerts {
+    cert: string;
+    key: string;
+}
+export declare function runRoost(args: string[], options?: RunRoostOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function getDomainPath(kind: "cert" | "key", domain: string, options?: DomainPathOptions): Promise<string>;
+export declare function getDomainCertPath(domain: string, options?: DomainPathOptions): Promise<string>;
+export declare function getDomainKeyPath(domain: string, options?: DomainPathOptions): Promise<string>;
+/**
+ * Resolve both cert and key **paths** for a domain in one call.
+ *
+ * @param domain - Domain name (e.g. "api.local")
+ * @param options - Optional { generate, exact, allow } and/or exec options
+ * @returns Promise resolving to `{ cert: string, key: string }` (filesystem paths)
+ */
+export declare function getDomainPaths(domain: string, options?: DomainPathOptions): Promise<DomainPaths>;
+/**
+ * Resolve both cert and key **contents** (literal PEM strings) for a domain in one call.
+ * Build-tool friendly: pass the result directly to HTTPS config—no file reads needed.
+ * Use `generate: true` to create the domain if it doesn't exist.
+ *
+ * @param domain - Domain name (e.g. "api.local")
+ * @param options - Optional { generate, exact, allow } and/or exec options
+ * @returns Promise resolving to `{ cert: string, key: string }` (PEM file contents)
+ */
+export declare function getDomainCerts(domain: string, options?: DomainPathOptions): Promise<DomainCerts>;

package/index.js

@@ -0,0 +1,112 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRoost = runRoost;
+exports.getDomainPath = getDomainPath;
+exports.getDomainCertPath = getDomainCertPath;
+exports.getDomainKeyPath = getDomainKeyPath;
+exports.getDomainPaths = getDomainPaths;
+exports.getDomainCerts = getDomainCerts;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const PATH_OPTION_KEYS = ["generate", "exact", "allow"];
+function getBinaryPath() {
+    const exeName = process.platform === "win32" ? "roost.exe" : "roost";
+    const exePath = path_1.default.join(__dirname, "bin", exeName);
+    if (!fs_1.default.existsSync(exePath)) {
+        const error = new Error("roost: binary not found. Make sure @itsbjoern/roost is installed and the postinstall step completed successfully.");
+        error.code = "ENOENT";
+        throw error;
+    }
+    return exePath;
+}
+function runRoost(args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const exePath = getBinaryPath();
+        (0, child_process_1.execFile)(exePath, args, {
+            encoding: "utf8",
+            ...options,
+        }, (error, stdout, stderr) => {
+            const out = typeof stdout === "string" ? stdout : stdout?.toString() ?? "";
+            const err = typeof stderr === "string" ? stderr : stderr?.toString() ?? "";
+            if (error) {
+                error.stdout = out;
+                error.stderr = err;
+                reject(error);
+                return;
+            }
+            resolve({ stdout: out, stderr: err });
+        });
+    });
+}
+function domainPathArgs(kind, domain, pathOptions = {}) {
+    const args = ["domain", "path", kind, domain];
+    if (pathOptions.generate)
+        args.push("--generate");
+    if (pathOptions.exact)
+        args.push("--exact");
+    if (pathOptions.allow)
+        args.push("--allow");
+    return args;
+}
+async function getDomainPath(kind, domain, options = {}) {
+    if (kind !== "cert" && kind !== "key") {
+        throw new Error(`Invalid kind "${kind}". Expected "cert" or "key".`);
+    }
+    if (!domain) {
+        throw new Error("Domain is required.");
+    }
+    const pathOptions = {};
+    const execOptions = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (PATH_OPTION_KEYS.includes(key)) {
+            pathOptions[key] = value;
+        }
+        else {
+            execOptions[key] = value;
+        }
+    }
+    const args = domainPathArgs(kind, domain, pathOptions);
+    const { stdout } = await runRoost(args, execOptions);
+    return stdout.trim();
+}
+async function getDomainCertPath(domain, options = {}) {
+    return getDomainPath("cert", domain, options);
+}
+async function getDomainKeyPath(domain, options = {}) {
+    return getDomainPath("key", domain, options);
+}
+/**
+ * Resolve both cert and key **paths** for a domain in one call.
+ *
+ * @param domain - Domain name (e.g. "api.local")
+ * @param options - Optional { generate, exact, allow } and/or exec options
+ * @returns Promise resolving to `{ cert: string, key: string }` (filesystem paths)
+ */
+async function getDomainPaths(domain, options = {}) {
+    const [cert, key] = await Promise.all([
+        getDomainCertPath(domain, options),
+        getDomainKeyPath(domain, options),
+    ]);
+    return { cert, key };
+}
+/**
+ * Resolve both cert and key **contents** (literal PEM strings) for a domain in one call.
+ * Build-tool friendly: pass the result directly to HTTPS config—no file reads needed.
+ * Use `generate: true` to create the domain if it doesn't exist.
+ *
+ * @param domain - Domain name (e.g. "api.local")
+ * @param options - Optional { generate, exact, allow } and/or exec options
+ * @returns Promise resolving to `{ cert: string, key: string }` (PEM file contents)
+ */
+async function getDomainCerts(domain, options = {}) {
+    const paths = await getDomainPaths(domain, options);
+    const [cert, key] = await Promise.all([
+        fs_1.default.promises.readFile(paths.cert, "utf8"),
+        fs_1.default.promises.readFile(paths.key, "utf8"),
+    ]);
+    return { cert, key };
+}

package/install.js

@@ -112,16 +112,26 @@ async function main() {
       cwd: binDir,
     });
 
-    const exeName = process.platform === "win32" ? "roost.exe" : "roost";
-    const binPath = path.join(binDir, exeName);
+    const extractedName = process.platform === "win32" ? "roost.exe" : "roost";
+    const extractedPath = path.join(binDir, extractedName);
 
-    const exists = fs.existsSync(binPath);
+    const exists = fs.existsSync(extractedPath);
     if (!exists) {
       throw new Error(
-        `Extracted archive did not contain expected binary at ${binPath}`
+        `Extracted archive did not contain expected binary at ${extractedPath}`
       );
     }
 
+    // On Unix, archive contains "roost" which would overwrite the Node wrapper.
+    // Rename to roost-bin so bin/roost stays as the wrapper script.
+    let binPath;
+    if (process.platform === "win32") {
+      binPath = extractedPath; // already bin/roost.exe
+    } else {
+      binPath = path.join(binDir, "roost-bin");
+      await fs.promises.rename(extractedPath, binPath);
+    }
+
     if (process.platform !== "win32") {
       await fs.promises.chmod(binPath, 0o755);
     }

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@itsbjoern/roost",
-  "version": "0.1.4",
+  "version": "0.1.8",
   "description": "Roost CLI - local HTTPS reverse proxy with automatic cert management",
+  "main": "index.js",
+  "types": "index.d.ts",
   "bin": {
     "roost": "bin/roost"
   },
   "scripts": {
-    "postinstall": "node install.js"
+    "build": "tsc",
+    "postinstall": "node install.js",
+    "prepublishOnly": "npm run build"
   },
   "files": [
+    "index.js",
+    "index.d.ts",
     "bin/",
     "install.js",
     "README.md"
@@ -33,11 +39,15 @@
   },
   "homepage": "https://github.com/itsbjoern/roost#readme",
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "dependencies": {
     "tar": "^7.4.3"
   },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
   "publishConfig": {
     "access": "public"
   }

package/bin/roost

@@ -1,35 +0,0 @@
-#!/usr/bin/env node
-
-const fs = require("fs");
-const path = require("path");
-const { spawn } = require("child_process");
-
-function run() {
-  const exeName = process.platform === "win32" ? "roost.exe" : "roost";
-  const exePath = path.join(__dirname, exeName);
-
-  if (!fs.existsSync(exePath)) {
-    console.error(
-      "roost: binary not found. Try reinstalling:\n" +
-        "  npm uninstall -g @itsbjoern/roost && npm install -g @itsbjoern/roost\n" +
-        "or download a release binary / build from source:\n" +
-        "  https://github.com/itsbjoern/roost#install"
-    );
-    process.exit(1);
-  }
-
-  const child = spawn(exePath, process.argv.slice(2), {
-    stdio: "inherit",
-  });
-
-  child.on("exit", (code, signal) => {
-    if (signal) {
-      process.kill(process.pid, signal);
-    } else {
-      process.exit(code == null ? 1 : code);
-    }
-  });
-}
-
-run();
-