graphonomous 0.1.0

package/README.md

@@ -0,0 +1,210 @@
+# graphonomous (npm wrapper)
+
+This package provides an npm-friendly launcher for the Graphonomous MCP server CLI.
+
+It installs (or reuses) a platform-specific `graphonomous` binary and exposes:
+
+- `graphonomous ...`
+- `npx graphonomous ...`
+
+The underlying server communicates over **STDIO**, so it works well with MCP-capable editors/clients (for example Zed custom context servers).
+
+---
+
+## What this package does
+
+- Detects your OS/arch (`darwin|linux` + `x64|arm64`)
+- Downloads a matching release asset at install time
+- Installs the OTP release command path under `vendor/<platform>-<arch>/graphonomous/bin/graphonomous` when available
+- Creates/uses `vendor/<platform>-<arch>/graphonomous` as the launcher target for consistent execution
+- Runs the resolved Graphonomous command with all arguments passed through
+
+---
+
+## Requirements
+
+- Node.js `>= 18`
+- Supported platforms:
+  - macOS: `x64`, `arm64`
+  - Linux: `x64`, `arm64`
+
+---
+
+## Install
+
+### Global install
+
+```sh
+npm i -g graphonomous
+```
+
+Then run:
+
+```sh
+graphonomous --help
+```
+
+### One-off execution
+
+```sh
+npx -y graphonomous --help
+```
+
+### Local project install
+
+```sh
+npm i graphonomous
+npx graphonomous --help
+```
+
+---
+
+## Run examples
+
+Start Graphonomous MCP server with a local DB path:
+
+```sh
+graphonomous --db ~/.graphonomous/knowledge.db --embedder-backend fallback
+```
+
+Safe laptop-oriented defaults:
+
+```sh
+graphonomous \
+  --db ~/.graphonomous/knowledge.db \
+  --embedder-backend fallback \
+  --log-level info
+```
+
+---
+
+## Zed configuration example
+
+In Zed settings JSON:
+
+```json
+{
+  "context_servers": {
+    "graphonomous": {
+      "command": "graphonomous",
+      "args": ["--db", "~/.graphonomous/knowledge.db", "--embedder-backend", "fallback"],
+      "env": {
+        "GRAPHONOMOUS_EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
+      }
+    }
+  }
+}
+```
+
+If you prefer not to install globally:
+
+```json
+{
+  "context_servers": {
+    "graphonomous": {
+      "command": "npx",
+      "args": ["-y", "graphonomous", "--db", "~/.graphonomous/knowledge.db", "--embedder-backend", "fallback"],
+      "env": {}
+    }
+  }
+}
+```
+
+---
+
+## Release asset override instructions
+
+The installer supports override environment variables for custom repos/tags/asset hosting.
+
+### Override GitHub owner/repo/tag
+
+```sh
+GRAPHONOMOUS_GITHUB_OWNER=my-org \
+GRAPHONOMOUS_GITHUB_REPO=graphonomous \
+GRAPHONOMOUS_RELEASE_TAG=v0.1.0 \
+npm i graphonomous
+```
+
+### Override version used for asset naming
+
+```sh
+GRAPHONOMOUS_VERSION=0.1.0 npm i graphonomous
+```
+
+### Use custom release base URL (bypass GitHub release URL construction)
+
+`GRAPHONOMOUS_RELEASE_BASE_URL` should point to a directory containing assets named like:
+
+`graphonomous-v<version>-<platform>-<arch>.tar.gz`
+
+Example:
+
+```sh
+GRAPHONOMOUS_RELEASE_BASE_URL=https://downloads.example.com/graphonomous \
+GRAPHONOMOUS_VERSION=0.1.0 \
+npm i graphonomous
+```
+
+### Private release download token
+
+```sh
+GRAPHONOMOUS_GITHUB_TOKEN=ghp_xxx npm i graphonomous
+```
+
+(You can also use `GITHUB_TOKEN`.)
+
+### Skip, force, and tune download behavior
+
+```sh
+# Skip download entirely
+GRAPHONOMOUS_SKIP_DOWNLOAD=1 npm i graphonomous
+
+# Force re-download even if binary exists
+GRAPHONOMOUS_FORCE_DOWNLOAD=1 npm i graphonomous
+
+# Timeout and redirect controls
+GRAPHONOMOUS_DOWNLOAD_TIMEOUT_MS=120000 \
+GRAPHONOMOUS_DOWNLOAD_MAX_REDIRECTS=10 \
+npm i graphonomous
+```
+
+---
+
+### Runtime command override
+
+You can bypass installed vendor binaries/release layout and point directly to a custom executable:
+
+```sh
+GRAPHONOMOUS_BINARY_PATH=/absolute/path/to/graphonomous graphonomous --help
+```
+
+---
+
+## Troubleshooting
+
+### Binary not found after install
+Try reinstalling or rebuilding:
+
+```sh
+npm rebuild graphonomous
+# or
+npm i graphonomous@latest
+```
+
+### Unsupported platform message
+Current prebuilt targets are Linux/macOS + x64/arm64.
+
+### Permission issue on command path
+Reinstall the package, or manually set executable bit on unix-like systems:
+
+```sh
+chmod +x node_modules/graphonomous/vendor/<target>/graphonomous
+chmod +x node_modules/graphonomous/vendor/<target>/graphonomous/bin/graphonomous
+```
+
+---
+
+## Source of truth
+
+The npm package is a distribution wrapper around the Graphonomous Elixir CLI.  
+Core implementation and release process live in the Graphonomous repository.

package/bin/graphonomous.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * npm bin launcher for Graphonomous.
+ *
+ * This script resolves the installed platform-specific Graphonomous command in:
+ *   npm/vendor/<platform>-<arch>/graphonomous/bin/graphonomous
+ *
+ * For OTP release assets, it executes the release command through:
+ *   eval "Graphonomous.CLI.main(System.argv())"
+ * and passes through all CLI arguments.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+const {
+  resolvePlatform,
+  isSupportedPlatform,
+} = require("../scripts/resolve-platform");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const VENDOR_ROOT = path.join(PACKAGE_ROOT, "vendor");
+
+function fail(message, code = 1) {
+  console.error(`[graphonomous] ${message}`);
+  process.exit(code);
+}
+
+function fileExists(p) {
+  try {
+    fs.accessSync(p, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isExecutable(p) {
+  try {
+    fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveBinaryPath() {
+  const override = process.env.GRAPHONOMOUS_BINARY_PATH;
+  if (override && override.trim()) {
+    const candidate = path.resolve(override.trim());
+    if (!fileExists(candidate)) {
+      fail(
+        `GRAPHONOMOUS_BINARY_PATH is set but file does not exist: ${candidate}`,
+      );
+    }
+    return candidate;
+  }
+
+  if (!isSupportedPlatform(process.platform, process.arch)) {
+    fail(
+      `Unsupported platform "${process.platform}-${process.arch}". ` +
+        `Supported targets: darwin/linux + x64/arm64.`,
+    );
+  }
+
+  const info = resolvePlatform({
+    platform: process.platform,
+    arch: process.arch,
+  });
+
+  // Preferred layout for OTP release assets.
+  const releaseCommandPath = path.join(
+    VENDOR_ROOT,
+    info.target,
+    "graphonomous",
+    "bin",
+    info.exeName,
+  );
+
+  if (fileExists(releaseCommandPath)) {
+    return releaseCommandPath;
+  }
+
+  // Backward-compatible fallback for single-file binary assets.
+  const binaryPath = path.join(VENDOR_ROOT, info.target, info.exeName);
+  if (fileExists(binaryPath)) {
+    return binaryPath;
+  }
+
+  fail(
+    `Installed Graphonomous command not found.\n` +
+      `Checked:\n` +
+      `  - ${releaseCommandPath}\n` +
+      `  - ${binaryPath}\n` +
+      `Try reinstalling package or rerunning install scripts:\n` +
+      `  npm rebuild graphonomous\n` +
+      `or\n` +
+      `  npm i graphonomous@latest`,
+  );
+}
+
+function run() {
+  const binaryPath = resolveBinaryPath();
+
+  // Best-effort chmod for unix-like systems if executable bit is missing.
+  if (process.platform !== "win32" && !isExecutable(binaryPath)) {
+    try {
+      fs.chmodSync(binaryPath, 0o755);
+    } catch {
+      // ignore; spawn will report if it still cannot execute
+    }
+  }
+
+  const args = process.argv.slice(2);
+  const otpReleasePathPattern = new RegExp(
+    `[\\\\/]graphonomous[\\\\/]bin[\\\\/]graphonomous$`,
+  );
+  const spawnArgs = otpReleasePathPattern.test(binaryPath)
+    ? ["eval", "Graphonomous.CLI.main(System.argv())", ...args]
+    : args;
+
+  const child = spawn(binaryPath, spawnArgs, {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  child.on("error", (err) => {
+    fail(`Failed to start binary at ${binaryPath}: ${err.message}`);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      // Mirror termination signal behavior.
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(typeof code === "number" ? code : 1);
+  });
+
+  // Forward common termination signals to child.
+  const forward = (sig) => {
+    if (!child.killed) {
+      try {
+        child.kill(sig);
+      } catch {
+        // no-op
+      }
+    }
+  };
+
+  process.on("SIGINT", () => forward("SIGINT"));
+  process.on("SIGTERM", () => forward("SIGTERM"));
+}
+
+run();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "graphonomous",
+  "version": "0.1.0",
+  "description": "npm wrapper for the Graphonomous MCP server CLI",
+  "private": false,
+  "license": "UNLICENSED",
+  "author": "Ampersandbox",
+  "homepage": "https://github.com/ampersandbox/graphonomous#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ampersandbox/graphonomous.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ampersandbox/graphonomous/issues"
+  },
+  "type": "commonjs",
+  "bin": {
+    "graphonomous": "bin/graphonomous.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "vendor",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall.js",
+    "start": "node ./bin/graphonomous.js --help"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "graphonomous",
+    "ai",
+    "agent",
+    "elixir",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/scripts/download-release-asset.js

@@ -0,0 +1,274 @@
+"use strict";
+
+const fs = require("fs");
+const fsp = require("fs/promises");
+const path = require("path");
+const os = require("os");
+const http = require("http");
+const https = require("https");
+const { pipeline } = require("stream/promises");
+const { spawn } = require("child_process");
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_REDIRECTS = 5;
+
+function normalizeTag(tag) {
+  if (!tag || typeof tag !== "string") {
+    throw new Error("A release tag is required (e.g. v0.1.0).");
+  }
+  return tag.startsWith("v") ? tag : `v${tag}`;
+}
+
+function buildGitHubReleaseAssetUrl({ owner, repo, tag, assetName }) {
+  if (!owner) throw new Error("Missing GitHub owner.");
+  if (!repo) throw new Error("Missing GitHub repo.");
+  if (!assetName) throw new Error("Missing release asset name.");
+  const normalizedTag = normalizeTag(tag);
+  return `https://github.com/${owner}/${repo}/releases/download/${normalizedTag}/${assetName}`;
+}
+
+function ensureDir(dirPath) {
+  return fsp.mkdir(dirPath, { recursive: true });
+}
+
+function streamRequestToFile(url, destinationPath, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxRedirects = opts.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+  const headers = { ...(opts.headers || {}) };
+
+  return new Promise((resolve, reject) => {
+    const visited = [];
+    let settled = false;
+
+    const onError = (err) => {
+      if (!settled) {
+        settled = true;
+        reject(err);
+      }
+    };
+
+    const requestUrl = (targetUrl, redirectsLeft) => {
+      visited.push(targetUrl);
+
+      if (redirectsLeft < 0) {
+        onError(
+          new Error(
+            `Too many redirects while downloading release asset. Visited: ${visited.join(" -> ")}`
+          )
+        );
+        return;
+      }
+
+      const parsed = new URL(targetUrl);
+      const client = parsed.protocol === "http:" ? http : https;
+
+      const req = client.get(
+        targetUrl,
+        {
+          headers: {
+            "user-agent": "graphonomous-npm-installer",
+            ...headers
+          },
+          timeout: timeoutMs
+        },
+        async (res) => {
+          const status = res.statusCode || 0;
+
+          // Follow redirects
+          if (status >= 300 && status < 400 && res.headers.location) {
+            res.resume();
+            const nextUrl = new URL(res.headers.location, targetUrl).toString();
+            requestUrl(nextUrl, redirectsLeft - 1);
+            return;
+          }
+
+          if (status < 200 || status >= 300) {
+            const chunks = [];
+            for await (const chunk of res) chunks.push(chunk);
+            const body = Buffer.concat(chunks).toString("utf8");
+            onError(
+              new Error(
+                `Failed downloading asset. HTTP ${status}. URL=${targetUrl}${
+                  body ? `\nResponse: ${body.slice(0, 2000)}` : ""
+                }`
+              )
+            );
+            return;
+          }
+
+          try {
+            await ensureDir(path.dirname(destinationPath));
+            await pipeline(res, fs.createWriteStream(destinationPath));
+            if (!settled) {
+              settled = true;
+              resolve({ finalUrl: targetUrl, destinationPath });
+            }
+          } catch (err) {
+            onError(err);
+          }
+        }
+      );
+
+      req.on("timeout", () => {
+        req.destroy(new Error(`Download timed out after ${timeoutMs}ms`));
+      });
+
+      req.on("error", onError);
+    };
+
+    requestUrl(url, maxRedirects);
+  });
+}
+
+function runTarExtract({ archivePath, destinationDir, stripComponents = 0 }) {
+  return new Promise((resolve, reject) => {
+    const args = ["-xzf", archivePath, "-C", destinationDir];
+    if (stripComponents > 0) {
+      args.push(`--strip-components=${stripComponents}`);
+    }
+
+    const child = spawn("tar", args, {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+
+    child.on("error", (err) => {
+      reject(
+        new Error(
+          `Failed to start tar process. Ensure 'tar' is available on this system.\n${err.message}`
+        )
+      );
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(
+        new Error(
+          `Failed to extract archive with tar (exit code ${code}).` +
+            (stderr ? `\n${stderr.trim()}` : "")
+        )
+      );
+    });
+  });
+}
+
+async function fileExists(filePath) {
+  try {
+    await fsp.access(filePath, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Downloads and extracts a release asset archive (tar.gz), then optionally marks
+ * the expected executable as executable.
+ *
+ * Options:
+ * - url: direct asset URL (optional if owner/repo/tag/assetName are provided)
+ * - owner, repo, tag, assetName: used to build GitHub release URL
+ * - destinationDir: where the archive should be extracted (required)
+ * - archivePath: optional explicit temp archive path
+ * - stripComponents: optional tar --strip-components value (default 0)
+ * - executableName: optional executable to chmod +x after extraction
+ * - timeoutMs: download timeout (default 60s)
+ * - maxRedirects: max redirects (default 5)
+ * - token: optional GitHub token for private assets
+ * - keepArchive: keep downloaded archive on disk (default false)
+ * - logger: optional logger object ({ info, warn, error })
+ */
+async function downloadAndExtractReleaseAsset(options = {}) {
+  const logger = options.logger || console;
+  const destinationDir = options.destinationDir;
+
+  if (!destinationDir) {
+    throw new Error("downloadAndExtractReleaseAsset: destinationDir is required.");
+  }
+
+  const stripComponents = Number.isInteger(options.stripComponents)
+    ? options.stripComponents
+    : 0;
+
+  const assetUrl =
+    options.url ||
+    buildGitHubReleaseAssetUrl({
+      owner: options.owner,
+      repo: options.repo,
+      tag: options.tag,
+      assetName: options.assetName
+    });
+
+  const archivePath =
+    options.archivePath ||
+    path.join(
+      os.tmpdir(),
+      `graphonomous-${Date.now()}-${Math.random().toString(16).slice(2)}.tar.gz`
+    );
+
+  const headers = {};
+  if (options.token && typeof options.token === "string") {
+    headers.authorization = `Bearer ${options.token}`;
+  }
+
+  await ensureDir(destinationDir);
+
+  logger.info?.(`Downloading Graphonomous release asset: ${assetUrl}`);
+  await streamRequestToFile(assetUrl, archivePath, {
+    timeoutMs: options.timeoutMs,
+    maxRedirects: options.maxRedirects,
+    headers
+  });
+
+  logger.info?.(`Extracting release asset into: ${destinationDir}`);
+  await runTarExtract({
+    archivePath,
+    destinationDir,
+    stripComponents
+  });
+
+  let executablePath = null;
+  if (options.executableName) {
+    executablePath = path.join(destinationDir, options.executableName);
+    const exists = await fileExists(executablePath);
+    if (!exists) {
+      throw new Error(
+        `Expected executable "${options.executableName}" not found after extraction at ${executablePath}.`
+      );
+    }
+
+    // Ensure executable bit is present on unix-like systems
+    await fsp.chmod(executablePath, 0o755);
+  }
+
+  if (!options.keepArchive) {
+    try {
+      await fsp.unlink(archivePath);
+    } catch {
+      // best-effort cleanup
+    }
+  }
+
+  return {
+    assetUrl,
+    archivePath,
+    destinationDir,
+    executablePath
+  };
+}
+
+module.exports = {
+  normalizeTag,
+  buildGitHubReleaseAssetUrl,
+  streamRequestToFile,
+  runTarExtract,
+  downloadAndExtractReleaseAsset
+};

package/scripts/postinstall.js

@@ -0,0 +1,221 @@
+// npm postinstall script for Graphonomous.
+// Downloads the platform-specific Graphonomous release binary into npm/vendor/<target>/.
+
+"use strict";
+
+const fs = require("fs");
+const fsp = require("fs/promises");
+const path = require("path");
+const { resolvePlatform, isSupportedPlatform } = require("./resolve-platform");
+const { downloadAndExtractReleaseAsset } = require("./download-release-asset");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const VENDOR_ROOT = path.join(PACKAGE_ROOT, "vendor");
+
+function readPackageJson() {
+  const pkgPath = path.join(PACKAGE_ROOT, "package.json");
+  const raw = fs.readFileSync(pkgPath, "utf8");
+  return JSON.parse(raw);
+}
+
+function envFlag(name, defaultValue = false) {
+  const raw = process.env[name];
+  if (raw == null) return defaultValue;
+  const normalized = String(raw).trim().toLowerCase();
+  return ["1", "true", "yes", "on"].includes(normalized);
+}
+
+function getConfig(pkg) {
+  const owner = process.env.GRAPHONOMOUS_GITHUB_OWNER || "ampersandbox";
+  const repo = process.env.GRAPHONOMOUS_GITHUB_REPO || "graphonomous";
+  const version = process.env.GRAPHONOMOUS_VERSION || pkg.version;
+  const tag =
+    process.env.GRAPHONOMOUS_RELEASE_TAG || `v${version.replace(/^v/, "")}`;
+  const token =
+    process.env.GRAPHONOMOUS_GITHUB_TOKEN || process.env.GITHUB_TOKEN || null;
+  const force = envFlag("GRAPHONOMOUS_FORCE_DOWNLOAD", false);
+  const skip = envFlag("GRAPHONOMOUS_SKIP_DOWNLOAD", false);
+  const timeoutMs = Number(
+    process.env.GRAPHONOMOUS_DOWNLOAD_TIMEOUT_MS || 60_000,
+  );
+  const maxRedirects = Number(
+    process.env.GRAPHONOMOUS_DOWNLOAD_MAX_REDIRECTS || 5,
+  );
+  const releaseBaseUrl = process.env.GRAPHONOMOUS_RELEASE_BASE_URL || null;
+
+  return {
+    owner,
+    repo,
+    version: version.replace(/^v/, ""),
+    tag,
+    token,
+    force,
+    skip,
+    timeoutMs: Number.isFinite(timeoutMs) ? timeoutMs : 60_000,
+    maxRedirects: Number.isFinite(maxRedirects) ? maxRedirects : 5,
+    releaseBaseUrl,
+  };
+}
+
+async function exists(filePath) {
+  try {
+    await fsp.access(filePath, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildAssetName(version, target) {
+  return `graphonomous-v${version}-${target}.tar.gz`;
+}
+
+function buildCustomAssetUrl(baseUrl, assetName) {
+  const trimmed = String(baseUrl).replace(/\/+$/, "");
+  return `${trimmed}/${assetName}`;
+}
+
+async function resolveInstalledCommandPath(targetDir, exeName) {
+  const direct = path.join(targetDir, exeName);
+  if (await exists(direct)) return direct;
+
+  const otpDirect = path.join(targetDir, "bin", exeName);
+  if (await exists(otpDirect)) return otpDirect;
+
+  const entries = await fsp.readdir(targetDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const nested = path.join(targetDir, entry.name, "bin", exeName);
+    if (await exists(nested)) return nested;
+  }
+
+  throw new Error(
+    `Could not locate installed Graphonomous command after extraction. ` +
+      `Expected one of: ${direct}, ${otpDirect}, or <release>/bin/${exeName}.`,
+  );
+}
+
+async function installCommandShim({ shimPath, sourceCommandPath }) {
+  const shimDir = path.dirname(shimPath);
+  const relativeTarget = path
+    .relative(shimDir, sourceCommandPath)
+    .replace(/\\/g, "/");
+
+  const script = `#!/usr/bin/env sh
+set -eu
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+exec "$SCRIPT_DIR/${relativeTarget}" "$@"
+`;
+
+  await fsp.writeFile(shimPath, script, { encoding: "utf8", mode: 0o755 });
+  await fsp.chmod(shimPath, 0o755);
+}
+
+async function writeInstallMetadata(targetDir, metadata) {
+  const metadataPath = path.join(targetDir, ".install-metadata.json");
+  await fsp.writeFile(metadataPath, JSON.stringify(metadata, null, 2), "utf8");
+}
+
+async function main() {
+  const pkg = readPackageJson();
+  const cfg = getConfig(pkg);
+
+  if (cfg.skip) {
+    console.log(
+      "[graphonomous] postinstall skipped (GRAPHONOMOUS_SKIP_DOWNLOAD is set).",
+    );
+    return;
+  }
+
+  if (!isSupportedPlatform(process.platform, process.arch)) {
+    console.warn(
+      `[graphonomous] Unsupported platform for prebuilt binaries: ${process.platform}-${process.arch}.`,
+    );
+    console.warn(
+      "[graphonomous] Install continues without binary. You can build Graphonomous manually from source.",
+    );
+    return;
+  }
+
+  const platformInfo = resolvePlatform({
+    platform: process.platform,
+    arch: process.arch,
+    version: cfg.version,
+  });
+
+  const targetDir = path.join(VENDOR_ROOT, platformInfo.target);
+  const binaryPath = path.join(targetDir, platformInfo.exeName);
+  const assetName = buildAssetName(cfg.version, platformInfo.target);
+
+  if (!cfg.force && (await exists(binaryPath))) {
+    console.log(
+      `[graphonomous] Binary already present at ${binaryPath}; skipping download.`,
+    );
+    return;
+  }
+
+  const useCustomBaseUrl = Boolean(cfg.releaseBaseUrl);
+  const directUrl = useCustomBaseUrl
+    ? buildCustomAssetUrl(cfg.releaseBaseUrl, assetName)
+    : null;
+
+  console.log(
+    `[graphonomous] Installing Graphonomous binary for ${platformInfo.target} (version ${cfg.version})...`,
+  );
+
+  await downloadAndExtractReleaseAsset({
+    url: directUrl || undefined,
+    owner: cfg.owner,
+    repo: cfg.repo,
+    tag: cfg.tag,
+    assetName,
+    destinationDir: targetDir,
+    stripComponents: 0,
+    timeoutMs: cfg.timeoutMs,
+    maxRedirects: cfg.maxRedirects,
+    token: cfg.token,
+    keepArchive: false,
+    logger: console,
+  });
+
+  const installedCommandPath = await resolveInstalledCommandPath(
+    targetDir,
+    platformInfo.exeName,
+  );
+
+  if (installedCommandPath !== binaryPath) {
+    await installCommandShim({
+      shimPath: binaryPath,
+      sourceCommandPath: installedCommandPath,
+    });
+  } else {
+    await fsp.chmod(binaryPath, 0o755);
+  }
+
+  await writeInstallMetadata(targetDir, {
+    packageName: pkg.name,
+    packageVersion: pkg.version,
+    resolvedVersion: cfg.version,
+    tag: cfg.tag,
+    target: platformInfo.target,
+    binaryPath,
+    installedCommandPath,
+    installedAt: new Date().toISOString(),
+    source: useCustomBaseUrl
+      ? "custom_release_base_url"
+      : `github:${cfg.owner}/${cfg.repo}`,
+  });
+
+  console.log(`[graphonomous] Installed binary: ${binaryPath}`);
+  if (installedCommandPath !== binaryPath) {
+    console.log(
+      `[graphonomous] Installed command source: ${installedCommandPath}`,
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error("[graphonomous] postinstall failed.");
+  console.error(err && err.stack ? err.stack : err);
+  process.exitCode = 1;
+});

package/scripts/resolve-platform.js

@@ -0,0 +1,79 @@
+"use strict";
+
+/**
+ * Resolve Node.js runtime platform/architecture into Graphonomous binary artifact metadata.
+ *
+ * Supported targets:
+ * - darwin-x64
+ * - darwin-arm64
+ * - linux-x64
+ * - linux-arm64
+ */
+
+const PLATFORM_MAP = {
+  darwin: "darwin",
+  linux: "linux"
+};
+
+const ARCH_MAP = {
+  x64: "x64",
+  arm64: "arm64"
+};
+
+function normalizeVersion(version) {
+  if (!version || typeof version !== "string") {
+    throw new Error("A package version string is required.");
+  }
+
+  return version.startsWith("v") ? version.slice(1) : version;
+}
+
+function resolvePlatform(opts = {}) {
+  const rawPlatform = opts.platform || process.platform;
+  const rawArch = opts.arch || process.arch;
+  const version = opts.version ? normalizeVersion(opts.version) : null;
+
+  const platform = PLATFORM_MAP[rawPlatform];
+  const arch = ARCH_MAP[rawArch];
+
+  if (!platform) {
+    throw new Error(
+      `Unsupported platform "${rawPlatform}". Supported platforms: ${Object.keys(PLATFORM_MAP).join(", ")}.`
+    );
+  }
+
+  if (!arch) {
+    throw new Error(
+      `Unsupported architecture "${rawArch}". Supported architectures: ${Object.keys(ARCH_MAP).join(", ")}.`
+    );
+  }
+
+  const target = `${platform}-${arch}`;
+
+  const result = {
+    platform,
+    arch,
+    target,
+    exeName: platform === "windows" ? "graphonomous.exe" : "graphonomous",
+    archiveExt: "tar.gz"
+  };
+
+  if (version) {
+    result.version = version;
+    result.tag = `v${version}`;
+    result.archiveName = `graphonomous-v${version}-${target}.${result.archiveExt}`;
+  }
+
+  return result;
+}
+
+function isSupportedPlatform(platform = process.platform, arch = process.arch) {
+  return Boolean(PLATFORM_MAP[platform] && ARCH_MAP[arch]);
+}
+
+module.exports = {
+  PLATFORM_MAP,
+  ARCH_MAP,
+  resolvePlatform,
+  isSupportedPlatform
+};