@ryanstark24/sfgraph-cli 1.1.0

package/dist/commands/rebuild-bindings.js

@@ -0,0 +1,129 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+function detectPackageManager(installRoot) {
+    // installRoot looks like .../node_modules/better-sqlite3 or
+    // .../node_modules/.pnpm/better-sqlite3@x.y.z/node_modules/better-sqlite3.
+    // The .pnpm segment is the unambiguous tell.
+    return installRoot.includes(`${path.sep}.pnpm${path.sep}`) ? "pnpm" : "npm";
+}
+function findInstallRoot() {
+    // better-sqlite3 isn't a direct dep of @ryanstark24/sfgraph-cli — it's
+    // owned by @ryanstark24/sfgraph-core and @ryanstark24/sfgraph-server.
+    // Walk through one of those to find the actual binding, matching the
+    // resolution chain doctor.ts uses (so we rebuild the SAME copy that
+    // would have been loaded at runtime, not a workspace-root duplicate).
+    const here = createRequire(import.meta.url);
+    const chains = ["@ryanstark24/sfgraph-core", "@ryanstark24/sfgraph-server"];
+    for (const chain of chains) {
+        try {
+            const entry = here.resolve(chain);
+            const downstream = createRequire(entry);
+            const pkgPath = downstream.resolve("better-sqlite3/package.json");
+            return path.dirname(pkgPath);
+        }
+        catch {
+            // try next chain
+        }
+    }
+    // Last resort: maybe better-sqlite3 IS resolvable directly (CLI ran from
+    // a flat install layout, e.g. global npm with no workspace).
+    try {
+        const pkgPath = here.resolve("better-sqlite3/package.json");
+        return path.dirname(pkgPath);
+    }
+    catch {
+        return null;
+    }
+}
+function workspaceRootFor(installRoot) {
+    // For pnpm: walk up past the `.pnpm/<pkg>/node_modules/<pkg>` chain to
+    // the workspace root. For npm: parent of node_modules.
+    const parts = installRoot.split(path.sep);
+    const nodeModulesIdx = parts.lastIndexOf("node_modules");
+    if (nodeModulesIdx < 0)
+        return installRoot;
+    // For pnpm, there may be a deeper node_modules — find the outermost one.
+    const firstNodeModulesIdx = parts.indexOf("node_modules");
+    return parts.slice(0, firstNodeModulesIdx).join(path.sep) || path.sep;
+}
+export async function rebuildBindingsCmd(opts = {}) {
+    const installRoot = findInstallRoot();
+    if (!installRoot) {
+        console.error("sfgraph rebuild-bindings: better-sqlite3 not resolvable from this install.");
+        console.error("  Run `npm install` (or `pnpm install`) first, then re-run this command.");
+        process.exitCode = 1;
+        return;
+    }
+    if (!existsSync(installRoot)) {
+        console.error(`sfgraph rebuild-bindings: resolved install root does not exist: ${installRoot}`);
+        process.exitCode = 1;
+        return;
+    }
+    const pm = opts.packageManager ?? detectPackageManager(installRoot);
+    const cwd = workspaceRootFor(installRoot);
+    // pnpm and npm both accept `rebuild <pkg>`. --build-from-source forces a
+    // fresh compile even if a stale prebuilt is cached — necessary when the
+    // failure mode is "downloaded prebuilt for wrong ABI."
+    const args = pm === "pnpm"
+        ? ["rebuild", "better-sqlite3"]
+        : ["rebuild", "better-sqlite3", "--build-from-source"];
+    console.log(`sfgraph rebuild-bindings:`);
+    console.log(`  Node:           ${process.version} (ABI ${process.versions.modules})`);
+    console.log(`  Package mgr:    ${pm}`);
+    console.log(`  Workspace:      ${cwd}`);
+    console.log(`  Install root:   ${installRoot}`);
+    console.log(`  Command:        ${pm} ${args.join(" ")}`);
+    if (opts.dryRun) {
+        console.log("  (dry-run — no command executed)");
+        return;
+    }
+    console.log("");
+    console.log("Running rebuild — this typically takes 20–60s on first run…");
+    console.log("");
+    await new Promise((resolve, reject) => {
+        const child = spawn(pm, args, { cwd, stdio: "inherit", shell: false });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`${pm} ${args[0]} exited with code ${code}`));
+        });
+    }).catch((e) => {
+        console.error("");
+        console.error(`sfgraph rebuild-bindings: failed — ${e.message}`);
+        console.error("  Common cause: no C++ toolchain. Install one for your platform:");
+        console.error("    macOS:   xcode-select --install");
+        console.error("    Linux:   apt install build-essential python3   # Debian/Ubuntu");
+        console.error("             dnf groupinstall 'Development Tools' && dnf install python3   # Fedora/RHEL");
+        console.error("             pacman -S base-devel python   # Arch");
+        console.error("             apk add build-base python3   # Alpine (musl always rebuilds from source)");
+        console.error("    Windows: install Visual Studio Build Tools with the 'Desktop development with C++' workload,");
+        console.error("             then restart your shell so cl.exe is on PATH.");
+        process.exitCode = 1;
+    });
+    if (process.exitCode === 1)
+        return;
+    // Verify the rebuild actually produced a loadable binding for the
+    // current ABI. Doing this here turns "did it work?" from a separate
+    // `sfgraph doctor` round-trip into a single command.
+    try {
+        const req = createRequire(import.meta.url);
+        // Clear any cached failure from earlier in this process.
+        delete req.cache?.[req.resolve("better-sqlite3")];
+        req("better-sqlite3");
+        console.log("");
+        console.log("✓ better-sqlite3 loads cleanly for the current Node runtime.");
+        console.log("  Next: `sfgraph doctor` to verify org DBs open, then resume normal use.");
+    }
+    catch (e) {
+        console.error("");
+        console.error("✗ Rebuild completed but better-sqlite3 still fails to load:");
+        console.error(`  ${e.message.split("\n")[0]}`);
+        console.error("  Run `sfgraph doctor` for more detail.");
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=rebuild-bindings.js.map

package/dist/commands/rebuild-bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebuild-bindings.js","sourceRoot":"","sources":["../../src/commands/rebuild-bindings.ts"],"names":[],"mappings":"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"}

package/dist/commands/refresh-orgs.d.ts

@@ -0,0 +1,17 @@
+export interface RefreshOrgsOpts {
+    /** Override the data dir (where the snapshot is written). Defaults to
+     *  `getSfgraphPaths().data`. Useful in tests. */
+    dataDir?: string;
+    log?: (s: string) => void;
+}
+/**
+ * Re-snapshot `sf` CLI org state (alias map, default-org, authorizations)
+ * into `<dataDir>/orgs-snapshot.json`. The MCP child reads this snapshot
+ * when it can't reach `~/.sf/` directly (Cursor's macOS sandbox case).
+ *
+ * Run this whenever sf state changes (new login, alias change, target-org
+ * flipped) without having to re-do the full `sfgraph install` (which also
+ * rewrites MCP config + reinstalls skills).
+ */
+export declare function refreshOrgsCmd(opts?: RefreshOrgsOpts): Promise<void>;
+//# sourceMappingURL=refresh-orgs.d.ts.map

package/dist/commands/refresh-orgs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-orgs.d.ts","sourceRoot":"","sources":["../../src/commands/refresh-orgs.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B;qDACiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9E"}

package/dist/commands/refresh-orgs.js

@@ -0,0 +1,26 @@
+import { getSfgraphPaths } from "@ryanstark24/sfgraph-shared";
+import { ORG_SNAPSHOT_FILENAME, writeOrgSnapshot } from "./install.js";
+/**
+ * Re-snapshot `sf` CLI org state (alias map, default-org, authorizations)
+ * into `<dataDir>/orgs-snapshot.json`. The MCP child reads this snapshot
+ * when it can't reach `~/.sf/` directly (Cursor's macOS sandbox case).
+ *
+ * Run this whenever sf state changes (new login, alias change, target-org
+ * flipped) without having to re-do the full `sfgraph install` (which also
+ * rewrites MCP config + reinstalls skills).
+ */
+export async function refreshOrgsCmd(opts = {}) {
+    const log = opts.log ?? ((s) => console.log(s));
+    const dataDir = opts.dataDir ?? getSfgraphPaths().data;
+    try {
+        await writeOrgSnapshot(dataDir);
+        const path = `${dataDir}/${ORG_SNAPSHOT_FILENAME}`;
+        log(`✓ refreshed sf org snapshot at ${path}`);
+    }
+    catch (e) {
+        log(`✗ could not refresh: ${e.message}`);
+        log("  Hint: make sure `sf` is authenticated (run `sf org login web --alias <X>` first).");
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=refresh-orgs.js.map

package/dist/commands/refresh-orgs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-orgs.js","sourceRoot":"","sources":["../../src/commands/refresh-orgs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AASvE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAwB,EAAE;IAC7D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,eAAe,EAAE,CAAC,IAAI,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,GAAG,OAAO,IAAI,qBAAqB,EAAE,CAAC;QACnD,GAAG,CAAC,kCAAkC,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,GAAG,CAAC,wBAAyB,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;QACpD,GAAG,CAAC,qFAAqF,CAAC,CAAC;QAC3F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/commands/serve.d.ts

@@ -0,0 +1,8 @@
+export interface ServeOpts {
+    port: number;
+    host: string;
+    open: boolean;
+    iUnderstandPublicBind?: boolean;
+}
+export declare function serveCmd(opts: ServeOpts): Promise<void>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/commands/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAsID,wBAAsB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAqD7D"}

package/dist/commands/serve.js

@@ -0,0 +1,188 @@
+import { spawn, spawnSync } from "node:child_process";
+import { platform } from "node:os";
+/**
+ * Find PIDs holding the given TCP port in LISTEN state.
+ *   macOS / Linux: `lsof -ti tcp:<port> -sTCP:LISTEN`
+ *   Windows:      `netstat -ano` filtered to LISTENING lines on `:<port>`
+ * Returns an empty list if the probe fails, which triggers the normal
+ * EADDRINUSE error path (sane fallback — we never want this helper to
+ * raise into the user's error stream).
+ */
+function pidsOnPort(port) {
+    try {
+        if (platform() === "win32") {
+            const r = spawnSync("netstat", ["-ano"], { encoding: "utf8" });
+            if (r.status !== 0 || !r.stdout)
+                return [];
+            const pids = new Set();
+            // Lines look like:  TCP    127.0.0.1:7777    0.0.0.0:0    LISTENING    1234
+            // Match the trailing PID column on rows whose local address ends in
+            // `:<port>` and whose state is LISTENING. The `:port` suffix anchor
+            // matters — without it, a remote-side port match would false-positive.
+            const re = new RegExp(`\\s+TCP\\s+\\S+:${port}\\s+\\S+\\s+LISTENING\\s+(\\d+)`);
+            for (const line of r.stdout.split(/\r?\n/)) {
+                const m = re.exec(line);
+                if (m?.[1]) {
+                    const pid = Number.parseInt(m[1], 10);
+                    if (Number.isFinite(pid) && pid > 0)
+                        pids.add(pid);
+                }
+            }
+            return [...pids];
+        }
+        const lsof = spawnSync("lsof", ["-ti", `tcp:${port}`, "-sTCP:LISTEN"], { encoding: "utf8" });
+        if (lsof.status === 0 && lsof.stdout) {
+            return lsof.stdout
+                .split("\n")
+                .map((s) => Number.parseInt(s.trim(), 10))
+                .filter((n) => Number.isFinite(n) && n > 0);
+        }
+        // Fallback for Linux distros that don't ship lsof by default (Alpine,
+        // minimal Docker base images, some embedded distros). `ss` from
+        // iproute2 is near-universally available on modern Linux and emits
+        // pid info in the form `users:(("node",pid=1234,fd=21))`.
+        const ss = spawnSync("ss", ["-tlnpH", `sport = :${port}`], { encoding: "utf8" });
+        if (ss.status !== 0 || !ss.stdout)
+            return [];
+        const pids = new Set();
+        const re = /pid=(\d+)/g;
+        let m = re.exec(ss.stdout);
+        while (m !== null) {
+            const pid = Number.parseInt(m[1] ?? "", 10);
+            if (Number.isFinite(pid) && pid > 0)
+                pids.add(pid);
+            m = re.exec(ss.stdout);
+        }
+        return [...pids];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Terminate each pid.
+ *   Unix:    SIGTERM, brief grace period, then SIGKILL any survivors.
+ *   Windows: `taskkill /F /PID <pid>` — Windows has no SIGTERM/SIGKILL
+ *            distinction; TerminateProcess is the only primitive. /F
+ *            forces termination; without it, the call only delivers a
+ *            WM_CLOSE that GUI-less processes ignore.
+ * We only kill PIDs we identified as listening on OUR port — never a blind
+ * kill. Self-PID is filtered out as a safety belt.
+ */
+async function killPids(pids) {
+    const self = process.pid;
+    const targets = pids.filter((p) => p !== self);
+    if (targets.length === 0)
+        return;
+    if (platform() === "win32") {
+        for (const p of targets) {
+            try {
+                spawnSync("taskkill", ["/F", "/PID", String(p)], { stdio: "ignore" });
+            }
+            catch {
+                /* already gone or insufficient permissions */
+            }
+        }
+        // One tick so Windows releases the TCP bind before we retry listen.
+        await new Promise((r) => setTimeout(r, 250));
+        return;
+    }
+    for (const p of targets) {
+        try {
+            process.kill(p, "SIGTERM");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    // Brief grace period for clean shutdown, then escalate.
+    await new Promise((r) => setTimeout(r, 400));
+    for (const p of targets) {
+        try {
+            process.kill(p, 0); // probe — throws if gone
+            process.kill(p, "SIGKILL");
+        }
+        catch {
+            /* gone */
+        }
+    }
+    // One more tick so the kernel releases the bind.
+    await new Promise((r) => setTimeout(r, 150));
+}
+/**
+ * Hosts that bind only to the loopback interface. Anything else is reachable
+ * from the LAN (or, for `0.0.0.0`, from anyone the machine routes to). The
+ * web API has no auth — exposing it leaks the ingested org graph in full.
+ */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "::ffff:127.0.0.1"]);
+function isLoopback(host) {
+    return LOOPBACK_HOSTS.has(host.toLowerCase());
+}
+/** Open `url` in the user's default browser. Best-effort; failure is silent. */
+function openBrowser(url) {
+    const cmd = platform() === "darwin"
+        ? ["open", [url]]
+        : platform() === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd[0], cmd[1], {
+            stdio: "ignore",
+            detached: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* best effort */
+    }
+}
+export async function serveCmd(opts) {
+    if (!isLoopback(opts.host) && !opts.iUnderstandPublicBind) {
+        console.error(`sfgraph serve: refusing to bind to non-loopback host '${opts.host}' without --i-understand-public-bind.
+  The web API has no authentication; binding publicly exposes the full ingested org graph (schema, Apex names, relationships) to the LAN.
+  If this is what you want, re-run with --i-understand-public-bind.`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!isLoopback(opts.host)) {
+        console.warn(`sfgraph serve: WARNING — binding to '${opts.host}'. The web API has no auth; anyone reachable on this interface can read the entire ingested org graph.`);
+    }
+    const { startWebServer } = await import("@ryanstark24/sfgraph-web");
+    let handle;
+    try {
+        handle = await startWebServer({ port: opts.port, host: opts.host });
+    }
+    catch (e) {
+        const err = e;
+        if (err?.code !== "EADDRINUSE" || !isLoopback(opts.host))
+            throw err;
+        // Auto-recover: only happens when binding to loopback (the safe default
+        // path). For non-loopback binds we surface the original error — the
+        // process holding the port might not belong to us.
+        const pids = pidsOnPort(opts.port);
+        if (pids.length === 0) {
+            console.error(`sfgraph serve: port ${opts.port} is in use but I couldn't identify the holder. Pick another port with --port.`);
+            throw err;
+        }
+        console.log(`sfgraph serve: port ${opts.port} held by pid${pids.length > 1 ? "s" : ""} ${pids.join(", ")} — terminating and retrying…`);
+        await killPids(pids);
+        handle = await startWebServer({ port: opts.port, host: opts.host });
+    }
+    console.log(`\n  open ${handle.url} to explore the ingested graph(s)\n`);
+    if (opts.open)
+        openBrowser(handle.url);
+    // Block until SIGINT/SIGTERM, then shut down cleanly.
+    const stop = async (sig) => {
+        console.log(`\nsfgraph-web: received ${sig}, shutting down…`);
+        await handle.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void stop("SIGINT"));
+    process.on("SIGTERM", () => void stop("SIGTERM"));
+    // Keep the loop alive — the http server holds it, but be explicit so a
+    // future refactor that closes the listener doesn't accidentally drain
+    // the loop. (Same root cause as the post-object-phase silent-exit fix.)
+    await new Promise(() => { });
+}
+//# sourceMappingURL=serve.js.map

package/dist/commands/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AASnC;;;;;;;GAOG;AACH,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,CAAC;QACH,IAAI,QAAQ,EAAE,KAAK,OAAO,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,SAAS,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YAC/D,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;gBAAE,OAAO,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,4EAA4E;YAC5E,oEAAoE;YACpE,oEAAoE;YACpE,uEAAuE;YACvE,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,mBAAmB,IAAI,iCAAiC,CAAC,CAAC;YAChF,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3C,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACxB,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACX,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACtC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;wBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC;YACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QACnB,CAAC;QACD,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,IAAI,EAAE,EAAE,cAAc,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7F,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC,MAAM;iBACf,KAAK,CAAC,IAAI,CAAC;iBACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;iBACzC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAChD,CAAC;QACD,sEAAsE;QACtE,gEAAgE;QAChE,mEAAmE;QACnE,0DAA0D;QAC1D,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,YAAY,IAAI,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;QACjF,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM;YAAE,OAAO,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,EAAE,GAAG,YAAY,CAAC;QACxB,IAAI,CAAC,GAA2B,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QACnD,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;YAC5C,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACnD,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,QAAQ,CAAC,IAAc;IACpC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC;IACzB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAC/C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACjC,IAAI,QAAQ,EAAE,KAAK,OAAO,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,SAAS,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;YACxE,CAAC;YAAC,MAAM,CAAC;gBACP,8CAA8C;YAChD,CAAC;QACH,CAAC;QACD,oEAAoE;QACpE,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;IACD,wDAAwD;IACxD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7C,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,yBAAyB;YAC7C,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,UAAU;QACZ,CAAC;IACH,CAAC;IACD,iDAAiD;IACjD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC;AACtF,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,gFAAgF;AAChF,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,GAAG,GACP,QAAQ,EAAE,KAAK,QAAQ;QACrB,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC,CAAC,QAAQ,EAAE,KAAK,OAAO;YACtB,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAW,EAAE,GAAG,CAAC,CAAC,CAAa,EAAE;YACxD,KAAK,EAAE,QAAQ;YACf,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC5B,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAe;IAC5C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC1D,OAAO,CAAC,KAAK,CACX,yDAAyD,IAAI,CAAC,IAAI;;oEAEJ,CAC/D,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,IAAI,CACV,wCAAwC,IAAI,CAAC,IAAI,wGAAwG,CAC1J,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IACpE,IAAI,MAAkD,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,CAA0B,CAAC;QACvC,IAAI,GAAG,EAAE,IAAI,KAAK,YAAY,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,MAAM,GAAG,CAAC;QACpE,wEAAwE;QACxE,oEAAoE;QACpE,mDAAmD;QACnD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CACX,uBAAuB,IAAI,CAAC,IAAI,+EAA+E,CAChH,CAAC;YACF,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO,CAAC,GAAG,CACT,uBAAuB,IAAI,CAAC,IAAI,eAAe,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,8BAA8B,CAC3H,CAAC;QACF,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrB,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,YAAY,MAAM,CAAC,GAAG,qCAAqC,CAAC,CAAC;IACzE,IAAI,IAAI,CAAC,IAAI;QAAE,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAEvC,sDAAsD;IACtD,MAAM,IAAI,GAAG,KAAK,EAAE,GAAW,EAAE,EAAE;QACjC,OAAO,CAAC,GAAG,CAAC,2BAA2B,GAAG,kBAAkB,CAAC,CAAC;QAC9D,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAClD,uEAAuE;IACvE,sEAAsE;IACtE,wEAAwE;IACxE,MAAM,IAAI,OAAO,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAC9B,CAAC"}

package/dist/commands/snapshot.d.ts

@@ -0,0 +1,26 @@
+import { ConsoleLogger } from "@ryanstark24/sfgraph-shared";
+export interface SnapshotCommonOpts {
+    org?: string | undefined;
+    project?: string | undefined;
+}
+export interface SnapshotCreateOpts extends SnapshotCommonOpts {
+    label: string;
+    kind?: "manual" | "scheduled" | undefined;
+}
+export interface SnapshotDiffOpts extends SnapshotCommonOpts {
+    fromId: string;
+    toId: string;
+}
+export interface SnapshotPruneOpts extends SnapshotCommonOpts {
+    retainDays: number;
+}
+export interface SnapshotDeleteOpts extends SnapshotCommonOpts {
+    snapshotId: string;
+}
+export declare function snapshotListCmd(opts: SnapshotCommonOpts): Promise<void>;
+export declare function snapshotCreateCmd(opts: SnapshotCreateOpts): Promise<void>;
+export declare function snapshotDiffCmd(opts: SnapshotDiffOpts): Promise<void>;
+export declare function snapshotPruneCmd(opts: SnapshotPruneOpts): Promise<void>;
+export declare function snapshotDeleteCmd(opts: SnapshotDeleteOpts): Promise<void>;
+export { ConsoleLogger };
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/commands/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/commands/snapshot.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,aAAa,EAOd,MAAM,6BAA6B,CAAC;AAErC,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,UAAU,EAAE,MAAM,CAAC;CACpB;AA6CD,wBAAsB,eAAe,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuB7E;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe/E;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuC3E;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7E;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB/E;AAGD,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/commands/snapshot.js

@@ -0,0 +1,164 @@
+import path from "node:path";
+import { SqliteGraphStore, SqliteSnapshotStore, resolveDefaultOrgAlias, resolveOrg, } from "@ryanstark24/sfgraph-core";
+import { ConfigError, ConsoleLogger, SfgraphError, asOrgId, findProjectRoot, getSfgraphPaths, readWorkspace, safeOrgDbPath, } from "@ryanstark24/sfgraph-shared";
+async function resolveOrgId(opts) {
+    if (opts.org) {
+        const r = await resolveOrg(opts.org);
+        return String(r.orgId);
+    }
+    const startDir = opts.project ? path.resolve(opts.project) : process.cwd();
+    const projectRoot = findProjectRoot(startDir) ?? startDir;
+    const ws = await readWorkspace(projectRoot);
+    if (ws?.orgId)
+        return String(ws.orgId);
+    const alias = await resolveDefaultOrgAlias();
+    if (!alias) {
+        throw new ConfigError("snapshot: no --org provided, no workspace binding, and no default org configured.");
+    }
+    const r = await resolveOrg(alias);
+    return String(r.orgId);
+}
+async function openStores(orgId) {
+    const dbPath = safeOrgDbPath(getSfgraphPaths().data, orgId);
+    const graphStore = new SqliteGraphStore({ dbPath });
+    await graphStore.init();
+    const snapshotStore = new SqliteSnapshotStore({
+        dbPath,
+        db: graphStore.db,
+        skipMigrations: true,
+    });
+    await snapshotStore.init();
+    return { graphStore, snapshotStore };
+}
+function reportError(e) {
+    if (e instanceof SfgraphError) {
+        console.error(`[${e.code}] ${e.message}`);
+    }
+    else {
+        console.error(e.message);
+    }
+    process.exitCode = 1;
+}
+export async function snapshotListCmd(opts) {
+    try {
+        const orgId = await resolveOrgId(opts);
+        const { graphStore, snapshotStore } = await openStores(orgId);
+        try {
+            const snaps = snapshotStore.listSnapshots(asOrgId(orgId));
+            if (snaps.length === 0) {
+                console.log(`No snapshots for org ${orgId}.`);
+                return;
+            }
+            console.log("| ID | Label | Created | Auto |");
+            console.log("|---|---|---|---|");
+            for (const s of snaps) {
+                console.log(`| ${s.id} | ${s.label} | ${new Date(s.createdAt).toISOString()} | ${s.isAuto ? "yes" : "no"} |`);
+            }
+        }
+        finally {
+            await graphStore.close();
+        }
+    }
+    catch (e) {
+        reportError(e);
+    }
+}
+export async function snapshotCreateCmd(opts) {
+    try {
+        const orgId = await resolveOrgId(opts);
+        const { graphStore, snapshotStore } = await openStores(orgId);
+        try {
+            const kind = opts.kind ?? "manual";
+            const label = `${kind}:${opts.label}`;
+            const snap = snapshotStore.createSnapshot(asOrgId(orgId), label, false);
+            console.log(`Created snapshot ${snap.id} (label="${label}") for org ${orgId}.`);
+        }
+        finally {
+            await graphStore.close();
+        }
+    }
+    catch (e) {
+        reportError(e);
+    }
+}
+export async function snapshotDiffCmd(opts) {
+    try {
+        const orgId = await resolveOrgId(opts);
+        const { graphStore, snapshotStore } = await openStores(orgId);
+        try {
+            const to = opts.toId === "current" ? "current" : opts.toId;
+            const nodeDiff = snapshotStore.diffNodes(asOrgId(orgId), opts.fromId, to);
+            const edgeDiff = snapshotStore.diffEdges(asOrgId(orgId), opts.fromId, to);
+            console.log(`## Snapshot diff: ${opts.fromId} → ${opts.toId} (org ${orgId})`);
+            console.log("");
+            console.log(`**Nodes**: +${nodeDiff.added.length}  -${nodeDiff.removed.length}  ~${nodeDiff.changed.length}`);
+            console.log(`**Edges**: +${edgeDiff.added.length}  -${edgeDiff.removed.length}`);
+            console.log("");
+            if (nodeDiff.added.length > 0) {
+                console.log("### Added nodes");
+                for (const n of nodeDiff.added)
+                    console.log(`- ${n.label}: ${n.qualifiedName}`);
+            }
+            if (nodeDiff.removed.length > 0) {
+                console.log("");
+                console.log("### Removed nodes");
+                for (const n of nodeDiff.removed)
+                    console.log(`- ${n.label}: ${n.qualifiedName}`);
+            }
+            if (nodeDiff.changed.length > 0) {
+                console.log("");
+                console.log("### Changed nodes");
+                for (const { before, after } of nodeDiff.changed) {
+                    console.log(`- ${after.label}: ${after.qualifiedName} (hash ${before.sourceHash.slice(0, 8)}…→${after.sourceHash.slice(0, 8)}…)`);
+                }
+            }
+        }
+        finally {
+            await graphStore.close();
+        }
+    }
+    catch (e) {
+        reportError(e);
+    }
+}
+export async function snapshotPruneCmd(opts) {
+    try {
+        const orgId = await resolveOrgId(opts);
+        const { graphStore, snapshotStore } = await openStores(orgId);
+        try {
+            const n = snapshotStore.prune(asOrgId(orgId), opts.retainDays);
+            console.log(`Pruned ${n} auto-snapshot(s) older than ${opts.retainDays} days for org ${orgId}.`);
+        }
+        finally {
+            await graphStore.close();
+        }
+    }
+    catch (e) {
+        reportError(e);
+    }
+}
+export async function snapshotDeleteCmd(opts) {
+    try {
+        const orgId = await resolveOrgId(opts);
+        const { graphStore, snapshotStore } = await openStores(orgId);
+        try {
+            const existing = snapshotStore.getSnapshot(opts.snapshotId);
+            if (!existing) {
+                console.error(`snapshot ${opts.snapshotId} not found for org ${orgId}.`);
+                process.exitCode = 1;
+                return;
+            }
+            snapshotStore.deleteSnapshot(opts.snapshotId);
+            console.log(`Deleted snapshot ${opts.snapshotId} for org ${orgId}.`);
+        }
+        finally {
+            await graphStore.close();
+        }
+    }
+    catch (e) {
+        reportError(e);
+    }
+}
+// Silence unused-import warning when ConsoleLogger isn't referenced.
+export { ConsoleLogger };
+//# sourceMappingURL=snapshot.js.map

package/dist/commands/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/commands/snapshot.ts"],"names":[],"mappings":"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"}

package/dist/commands/telemetry.d.ts

@@ -0,0 +1,13 @@
+export interface TelemetryEnv {
+    configDir: string;
+    dataDir: string;
+    log: (s: string) => void;
+}
+export declare function defaultEnv(): TelemetryEnv;
+export declare function statusCmd(env?: TelemetryEnv): Promise<void>;
+export declare function enableLocalCmd(env?: TelemetryEnv): Promise<void>;
+export declare function disableCmd(env?: TelemetryEnv): Promise<void>;
+export declare function previewCmd(env?: TelemetryEnv): Promise<void>;
+export declare function purgeCmd(env?: TelemetryEnv): Promise<void>;
+export declare function resetIdCmd(env?: TelemetryEnv): Promise<void>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/commands/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/commands/telemetry.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1B;AAED,wBAAgB,UAAU,IAAI,YAAY,CAGzC;AAED,wBAAsB,SAAS,CAAC,GAAG,GAAE,YAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAK/E;AAED,wBAAsB,cAAc,CAAC,GAAG,GAAE,YAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAQpF;AAED,wBAAsB,UAAU,CAAC,GAAG,GAAE,YAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhF;AAED,wBAAsB,UAAU,CAAC,GAAG,GAAE,YAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhF;AAED,wBAAsB,QAAQ,CAAC,GAAG,GAAE,YAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9E;AAED,wBAAsB,UAAU,CAAC,GAAG,GAAE,YAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhF"}