graphify-sf 0.3.2

package/README.md

@@ -0,0 +1,70 @@
+# graphify-sf (npm)
+
+Install and run [graphify-sf](https://github.com/raykuonz/graphify-sf) — the Salesforce SFDX
+knowledge-graph tool — from npm, without needing Python.
+
+On install, a pre-built binary matching your OS/arch is downloaded from the GitHub Release.
+
+## Install
+
+```bash
+npm install graphify-sf
+# or
+pnpm add graphify-sf
+```
+
+> **pnpm note:** pnpm sets `ignore-scripts=true` by default, so the `postinstall` step may not
+> run automatically. The binary is downloaded lazily on first use instead, so everything still
+> works — you may just see a one-time download message the first time you invoke the CLI.
+
+## CLI usage
+
+```bash
+npx graphify-sf ./force-app --out my-graph-out --no-viz
+```
+
+The output directory will contain `graph.json` with the full knowledge graph.
+
+## Programmatic usage (Node.js / sf-cockpit)
+
+```js
+const { runGraphify } = require("graphify-sf");
+
+const { graphJsonPath } = await runGraphify("./force-app", { outDir: "my-graph-out" });
+console.log("Graph written to:", graphJsonPath);
+```
+
+`runGraphify` returns a Promise that resolves with `{ code, graphJsonPath }` on success and
+rejects on non-zero exit.
+
+Additional exports: `ensureBinary()` (downloads if missing, returns path), `binaryPath()`
+(returns expected path without triggering a download).
+
+## What's bundled
+
+This package wraps the **core static-extraction path** of graphify-sf: Apex, Flow, Object, LWC,
+Aura, Profile/PermSet, and Agentforce metadata — everything that can be parsed without an org
+connection. Community detection and the knowledge-graph JSON export are included.
+
+**Not bundled:** LLM-assisted extraction (`--backend`), SVG export, Neo4j export, MCP server, and
+file-watcher mode. Those extras require a full Python install:
+
+```bash
+pip install "graphify-sf[all]"
+# or
+pipx install "graphify-sf[all]"
+```
+
+## Supported platforms
+
+| Platform  | x64 | arm64 |
+|-----------|-----|-------|
+| linux     | ✓   | ✓     |
+| macOS     | ✓   | ✓     |
+| Windows   | ✓   | —     |
+
+For unsupported platforms, install via PyPI: `pipx install graphify-sf`.
+
+## License
+
+MIT — see [LICENSE](https://github.com/raykuonz/graphify-sf/blob/main/LICENSE).

package/bin/graphify-sf.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn } = require("child_process");
+const { ensureBinary } = require("../lib/download");
+
+ensureBinary()
+  .then((bin) => {
+    const child = spawn(bin, process.argv.slice(2), { stdio: "inherit" });
+    child.on("error", (err) => {
+      process.stderr.write(`graphify-sf: failed to start binary: ${err.message}\n`);
+      process.exit(1);
+    });
+    child.on("close", (code) => {
+      process.exit(code == null ? 1 : code);
+    });
+  })
+  .catch((err) => {
+    process.stderr.write(`graphify-sf: ${err.message}\n`);
+    process.exit(1);
+  });

package/index.js

@@ -0,0 +1,47 @@
+"use strict";
+
+const { spawn } = require("child_process");
+const path = require("path");
+const { ensureBinary, binaryPath } = require("./lib/download");
+
+/**
+ * Run graphify-sf programmatically.
+ *
+ * @param {string} sfdxPath - Path to the SFDX project root.
+ * @param {object} [options]
+ * @param {string} [options.outDir] - Output directory (default: "graphify-sf-out").
+ * @param {string[]} [options.extraArgs] - Additional CLI args forwarded verbatim.
+ * @param {"inherit"|"pipe"|"ignore"} [options.stdio] - stdio mode for the child process (default: "inherit").
+ * @returns {Promise<{code: number, graphJsonPath: string}>}
+ */
+async function runGraphify(sfdxPath, options) {
+  if (!sfdxPath) throw new Error("graphify-sf: sfdxPath is required");
+
+  const opts = options || {};
+  const outDir = opts.outDir || "graphify-sf-out";
+  const extraArgs = opts.extraArgs || [];
+  const stdioMode = opts.stdio || "inherit";
+
+  const bin = await ensureBinary();
+  const args = [sfdxPath, "--out", outDir, "--no-viz", ...extraArgs];
+  const graphJsonPath = path.join(outDir, "graph.json");
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: stdioMode });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ code, graphJsonPath });
+      } else {
+        reject(
+          new Error(
+            `graphify-sf exited with code ${code}. ` +
+              `Command: ${bin} ${args.join(" ")}`
+          )
+        );
+      }
+    });
+  });
+}
+
+module.exports = { runGraphify, ensureBinary, binaryPath };

package/install.js

@@ -0,0 +1,8 @@
+"use strict";
+
+const { download } = require("./lib/download");
+
+download().catch((err) => {
+  process.stderr.write(`graphify-sf postinstall failed: ${err.message}\n`);
+  process.exit(1);
+});

package/lib/download.js

@@ -0,0 +1,131 @@
+"use strict";
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+
+const PKG = require("../package.json");
+const VERSION = PKG.version;
+
+const SUPPORTED = {
+  linux: ["x64", "arm64"],
+  darwin: ["x64", "arm64"],
+  win32: ["x64"],
+};
+
+function assetName() {
+  const plat = process.platform;
+  const arch = process.arch;
+
+  const supported = SUPPORTED[plat];
+  if (!supported) {
+    throw new Error(
+      `graphify-sf: unsupported platform "${plat}". ` +
+        `Supported: ${Object.keys(SUPPORTED).join(", ")}. ` +
+        `Remediation: install via pip/pipx instead: pipx install graphify-sf`
+    );
+  }
+  if (!supported.includes(arch)) {
+    throw new Error(
+      `graphify-sf: unsupported arch "${arch}" on ${plat}. ` +
+        `Supported archs for ${plat}: ${supported.join(", ")}. ` +
+        `Remediation: install via pip/pipx instead: pipx install graphify-sf`
+    );
+  }
+
+  const ext = plat === "win32" ? ".exe" : "";
+  return `graphify-sf-${plat}-${arch}${ext}`;
+}
+
+function binDir() {
+  return path.join(__dirname, "..", "bin");
+}
+
+function binaryPath() {
+  const ext = process.platform === "win32" ? ".exe" : "";
+  return path.join(binDir(), `graphify-sf-bin${ext}`);
+}
+
+function downloadUrl(asset) {
+  return `https://github.com/raykuonz/graphify-sf/releases/download/v${VERSION}/${asset}`;
+}
+
+function fetchFollow(url, redirects) {
+  if (redirects === undefined) redirects = 5;
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { "User-Agent": "graphify-sf-npm-installer" } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          if (redirects === 0) {
+            reject(new Error(`graphify-sf: too many redirects downloading ${url}`));
+            return;
+          }
+          resolve(fetchFollow(res.headers.location, redirects - 1));
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(
+            new Error(
+              `graphify-sf: download failed with HTTP ${res.statusCode} from ${url}. ` +
+                `Remediation: install via pip/pipx instead: pipx install graphify-sf`
+            )
+          );
+          return;
+        }
+        resolve(res);
+      })
+      .on("error", reject);
+  });
+}
+
+async function download() {
+  const asset = assetName();
+  const url = downloadUrl(asset);
+  const dest = binaryPath();
+
+  fs.mkdirSync(binDir(), { recursive: true });
+
+  process.stdout.write(`graphify-sf: downloading ${asset} from ${url}\n`);
+
+  const res = await fetchFollow(url);
+
+  await new Promise((resolve, reject) => {
+    const tmp = dest + ".tmp";
+    const out = fs.createWriteStream(tmp);
+    res.pipe(out);
+    out.on("finish", () => {
+      out.close(() => {
+        try {
+          fs.renameSync(tmp, dest);
+          resolve();
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+    out.on("error", (e) => {
+      fs.unlink(tmp, () => {});
+      reject(e);
+    });
+    res.on("error", (e) => {
+      fs.unlink(tmp, () => {});
+      reject(e);
+    });
+  });
+
+  if (process.platform !== "win32") {
+    fs.chmodSync(dest, 0o755);
+  }
+
+  process.stdout.write(`graphify-sf: installed to ${dest}\n`);
+}
+
+async function ensureBinary() {
+  const dest = binaryPath();
+  if (!fs.existsSync(dest)) {
+    await download();
+  }
+  return dest;
+}
+
+module.exports = { assetName, binaryPath, binDir, download, ensureBinary };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "graphify-sf",
+  "version": "0.3.2",
+  "description": "Turn any Salesforce SFDX project into a queryable knowledge graph — no Python required.",
+  "bin": {
+    "graphify-sf": "bin/graphify-sf.js"
+  },
+  "main": "index.js",
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "index.js",
+    "install.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raykuonz/graphify-sf.git"
+  },
+  "homepage": "https://github.com/raykuonz/graphify-sf#readme",
+  "bugs": {
+    "url": "https://github.com/raykuonz/graphify-sf/issues"
+  }
+}