homebutler 0.0.1 → 0.7.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanghee Son (Higangssh)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,30 @@
 # homebutler
 
-**Manage your homelab from any AI — Claude, ChatGPT, Cursor, or terminal.**
+**Manage your homelab from any AI — Claude, ChatGPT, Cursor, or terminal. One binary. Zero dependencies.**
 
-This is a placeholder package. For the MCP server, install:
+This npm package downloads the homebutler Go binary and provides an MCP server wrapper.
+
+## Install
 
 ```bash
-npm install -g homebutler-mcp
+npm install -g homebutler
+```
+
+## Usage with MCP clients
+
+Add to your Claude Desktop / Cursor / Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "homebutler": {
+      "command": "npx",
+      "args": ["-y", "homebutler@latest"]
+    }
+  }
+}
 ```
 
-For the full CLI, visit: https://github.com/Higangssh/homebutler
+## Full documentation
+
+Visit: https://github.com/Higangssh/homebutler

package/install.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const { createWriteStream } = require("fs");
+const { pipeline } = require("stream/promises");
+
+const REPO = "Higangssh/homebutler";
+const BIN_NAME = process.platform === "win32" ? "homebutler.exe" : "homebutler";
+const BIN_DIR = path.join(__dirname, "bin");
+const BIN_PATH = path.join(BIN_DIR, BIN_NAME);
+
+function getPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  const osMap = { linux: "linux", darwin: "darwin", win32: "windows" };
+  const archMap = { x64: "amd64", arm64: "arm64" };
+
+  const os = osMap[platform];
+  const cpu = archMap[arch];
+
+  if (!os || !cpu) {
+    throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  }
+
+  return { os, cpu };
+}
+
+function fetchJSON(url) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { headers: { "User-Agent": "homebutler-mcp" }, timeout: 10000 }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetchJSON(res.headers.location).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode}`));
+      }
+      let data = "";
+      res.on("data", (c) => (data += c));
+      res.on("end", () => {
+        try { resolve(JSON.parse(data)); } catch (e) { reject(e); }
+      });
+    });
+    req.on("error", reject);
+    req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
+  });
+}
+
+async function getVersion() {
+  try {
+    const data = await fetchJSON(
+      `https://api.github.com/repos/${REPO}/releases/latest`
+    );
+    if (data.tag_name) return data.tag_name.replace(/^v/, "");
+  } catch {}
+  return require("./package.json").version;
+}
+
+function fetch(url) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { headers: { "User-Agent": "homebutler-mcp" }, timeout: 60000 }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetch(res.headers.location).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode} for ${url}`));
+      }
+      resolve(res);
+    });
+    req.on("error", reject);
+    req.on("timeout", () => { req.destroy(); reject(new Error("download timeout")); });
+  });
+}
+
+async function downloadAndExtract() {
+  const { os, cpu } = getPlatform();
+  const version = await getVersion();
+  const tag = `v${version}`;
+
+  const ext = os === "windows" ? "zip" : "tar.gz";
+  const assetName = `homebutler_${version}_${os}_${cpu}.${ext}`;
+  const url = `https://github.com/${REPO}/releases/download/${tag}/${assetName}`;
+
+  process.stderr.write(`Downloading homebutler ${tag} for ${os}/${cpu}...\n`);
+
+  fs.mkdirSync(BIN_DIR, { recursive: true });
+
+  const tmpFile = path.join(BIN_DIR, assetName);
+  const stream = createWriteStream(tmpFile);
+  const res = await fetch(url);
+  await pipeline(res, stream);
+
+  if (ext === "tar.gz") {
+    execSync(`tar -xzf "${tmpFile}" -C "${BIN_DIR}"`, { stdio: "pipe" });
+  } else {
+    execSync(`unzip -o "${tmpFile}" -d "${BIN_DIR}"`, { stdio: "pipe" });
+  }
+
+  // Find the binary (goreleaser puts it inside a directory or at root)
+  if (!fs.existsSync(BIN_PATH)) {
+    const found = findFile(BIN_DIR, BIN_NAME);
+    if (found && found !== BIN_PATH) {
+      fs.renameSync(found, BIN_PATH);
+    }
+  }
+
+  if (!fs.existsSync(BIN_PATH)) {
+    throw new Error(`Binary not found after extraction: ${BIN_PATH}`);
+  }
+
+  fs.chmodSync(BIN_PATH, 0o755);
+
+  // Cleanup
+  fs.unlinkSync(tmpFile);
+  for (const entry of fs.readdirSync(BIN_DIR)) {
+    const full = path.join(BIN_DIR, entry);
+    if (fs.statSync(full).isDirectory()) {
+      fs.rmSync(full, { recursive: true });
+    }
+  }
+
+  process.stderr.write(`homebutler ${tag} installed successfully.\n`);
+}
+
+function findFile(dir, name) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isFile() && entry.name === name) return full;
+    if (entry.isDirectory()) {
+      const found = findFile(full, name);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+async function main() {
+  // Skip if binary already exists and is correct version
+  if (fs.existsSync(BIN_PATH)) {
+    try {
+      const version = await getVersion();
+      const out = execSync(`"${BIN_PATH}" version`, { encoding: "utf8" });
+      if (out.includes(version)) {
+        process.stderr.write(`homebutler ${version} already installed.\n`);
+        process.exit(0);
+      }
+    } catch {}
+  }
+
+  await downloadAndExtract();
+}
+
+main().catch((err) => {
+  process.stderr.write(`Failed to install homebutler: ${err.message}\n`);
+  // Don't exit(1) during postinstall — let run.js handle lazy install
+  // This prevents npm install -g from failing if download is slow
+  if (process.env.npm_lifecycle_event === "postinstall") {
+    process.stderr.write("Binary will be downloaded on first run.\n");
+    process.exit(0);
+  }
+  process.exit(1);
+});

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "homebutler",
-  "version": "0.0.1",
-  "description": "Homelab management CLI + MCP server. Use homebutler-mcp for the MCP server package.",
-  "keywords": ["homebutler", "homelab", "mcp", "server", "docker", "monitoring"],
+  "version": "0.7.4",
+  "description": "Homelab management CLI + MCP server — manage servers, Docker, ports, alerts via AI",
+  "keywords": [
+    "mcp",
+    "homelab",
+    "server",
+    "docker",
+    "claude",
+    "ai",
+    "devops",
+    "monitoring"
+  ],
   "license": "MIT",
   "author": "Higangssh",
   "repository": {
@@ -10,7 +19,22 @@
     "url": "https://github.com/Higangssh/homebutler"
   },
   "homepage": "https://github.com/Higangssh/homebutler",
+  "bugs": {
+    "url": "https://github.com/Higangssh/homebutler/issues"
+  },
+  "bin": {
+    "homebutler-mcp": "run.js"
+  },
   "scripts": {
-    "postinstall": "echo 'For the MCP server, use: npm install -g homebutler-mcp'"
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "install.js",
+    "run.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
   }
 }

package/run.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn, execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const BIN_NAME = process.platform === "win32" ? "homebutler.exe" : "homebutler";
+const BIN_PATH = path.join(__dirname, "bin", BIN_NAME);
+
+// Lazy install: download binary on first run if postinstall was skipped/failed
+if (!fs.existsSync(BIN_PATH)) {
+  console.error("homebutler binary not found, downloading...");
+  try {
+    execSync("node " + JSON.stringify(path.join(__dirname, "install.js")), {
+      stdio: "inherit",
+      timeout: 120000,
+    });
+  } catch (err) {
+    console.error("Failed to install homebutler:", err.message);
+    process.exit(1);
+  }
+}
+
+if (!fs.existsSync(BIN_PATH)) {
+  console.error("homebutler binary not found after install.");
+  process.exit(1);
+}
+
+const args = ["mcp", ...process.argv.slice(2)];
+
+const child = spawn(BIN_PATH, args, {
+  stdio: ["inherit", "inherit", "inherit"],
+});
+
+child.on("exit", (code) => process.exit(code ?? 0));
+child.on("error", (err) => {
+  console.error("Failed to start homebutler:", err.message);
+  process.exit(1);
+});