@rag-forge/shared 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Femi Adedayo
+
+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

@@ -0,0 +1,44 @@
+# @rag-forge/shared
+
+> Internal shared utilities for the RAG-Forge monorepo.
+
+This package contains low-level utilities shared between [`@rag-forge/cli`](https://www.npmjs.com/package/@rag-forge/cli) and [`@rag-forge/mcp`](https://www.npmjs.com/package/@rag-forge/mcp) — primarily the Python subprocess bridge that lets the TypeScript packages invoke the Python evaluator and pipeline.
+
+## Are you looking for the CLI?
+
+You probably want one of these instead:
+
+- **[@rag-forge/cli](https://www.npmjs.com/package/@rag-forge/cli)** — the `rag-forge` command-line interface (this is what you install if you want to use RAG-Forge)
+- **[@rag-forge/mcp](https://www.npmjs.com/package/@rag-forge/mcp)** — the MCP server for Claude Desktop and other agent clients
+
+## What's in this package
+
+`@rag-forge/shared` exposes a single primitive:
+
+```typescript
+import { runPythonModule, checkPythonAvailable } from "@rag-forge/shared";
+
+const result = await runPythonModule({
+  module: "rag_forge_evaluator.cli",
+  args: ["audit", "--golden-set", "eval/golden_set.json"],
+});
+
+console.log(result.stdout);
+```
+
+It spawns `uv run python -u -m <module> ...` via `execa`, captures stdout/stderr, and returns a structured result. The `-u` flag is critical — it disables Python's stdout block-buffering so long-running subprocesses (audits, indexing) stream output in real time on Windows non-TTY shells.
+
+## Why this is its own package
+
+The TypeScript build for `@rag-forge/cli` and `@rag-forge/mcp` would otherwise duplicate this code. Keeping it as an internal published package (rather than a workspace-only library) means the bridge stays versioned, testable in isolation, and easy to upgrade across consumers.
+
+External consumers can use it too if they're building their own RAG-Forge integrations in Node.js, but the surface area is intentionally minimal and the API may change between minor versions.
+
+## Documentation
+
+- **Repository:** [github.com/hallengray/rag-forge](https://github.com/hallengray/rag-forge)
+- **Issues:** [github.com/hallengray/rag-forge/issues](https://github.com/hallengray/rag-forge/issues)
+
+## License
+
+MIT — Femi Adedayo

package/dist/python-bridge.js

@@ -3,7 +3,7 @@ import { execa } from "execa";
 async function runPythonModule(options) {
   const { module, args = [], cwd } = options;
   try {
-    const result = await execa("uv", ["run", "python", "-m", module, ...args], {
+    const result = await execa("uv", ["run", "python", "-u", "-m", module, ...args], {
       cwd,
       reject: false,
       timeout: 3e5

package/dist/python-bridge.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/python-bridge.ts"],"sourcesContent":["import { execa } from \"execa\";\n\nexport interface PythonBridgeOptions {\n  module: string;\n  args?: string[];\n  cwd?: string;\n}\n\nexport interface PythonBridgeResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n}\n\nexport async function runPythonModule(options: PythonBridgeOptions): Promise<PythonBridgeResult> {\n  const { module, args = [], cwd } = options;\n\n  try {\n    const result = await execa(\"uv\", [\"run\", \"python\", \"-m\", module, ...args], {\n      cwd,\n      reject: false,\n      timeout: 300_000, // 5 minute timeout\n    });\n\n    return {\n      stdout: result.stdout,\n      stderr: result.stderr,\n      exitCode: result.exitCode ?? (result.signal ? 1 : 0),\n    };\n  } catch (error) {\n    const message = error instanceof Error ? error.message : \"Unknown error\";\n    return {\n      stdout: \"\",\n      stderr: message,\n      exitCode: 1,\n    };\n  }\n}\n\nexport async function checkPythonAvailable(): Promise<boolean> {\n  try {\n    const result = await execa(\"uv\", [\"run\", \"python\", \"--version\"], { reject: false });\n    return result.exitCode === 0;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";AAAA,SAAS,aAAa;AActB,eAAsB,gBAAgB,SAA2D;AAC/F,QAAM,EAAE,QAAQ,OAAO,CAAC,GAAG,IAAI,IAAI;AAEnC,MAAI;AACF,UAAM,SAAS,MAAM,MAAM,MAAM,CAAC,OAAO,UAAU,MAAM,QAAQ,GAAG,IAAI,GAAG;AAAA,MACzE;AAAA,MACA,QAAQ;AAAA,MACR,SAAS;AAAA;AAAA,IACX,CAAC;AAED,WAAO;AAAA,MACL,QAAQ,OAAO;AAAA,MACf,QAAQ,OAAO;AAAA,MACf,UAAU,OAAO,aAAa,OAAO,SAAS,IAAI;AAAA,IACpD;AAAA,EACF,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU;AACzD,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,UAAU;AAAA,IACZ;AAAA,EACF;AACF;AAEA,eAAsB,uBAAyC;AAC7D,MAAI;AACF,UAAM,SAAS,MAAM,MAAM,MAAM,CAAC,OAAO,UAAU,WAAW,GAAG,EAAE,QAAQ,MAAM,CAAC;AAClF,WAAO,OAAO,aAAa;AAAA,EAC7B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../src/python-bridge.ts"],"sourcesContent":["import { execa } from \"execa\";\n\nexport interface PythonBridgeOptions {\n  module: string;\n  args?: string[];\n  cwd?: string;\n}\n\nexport interface PythonBridgeResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n}\n\nexport async function runPythonModule(options: PythonBridgeOptions): Promise<PythonBridgeResult> {\n  const { module, args = [], cwd } = options;\n\n  try {\n    const result = await execa(\"uv\", [\"run\", \"python\", \"-u\", \"-m\", module, ...args], {\n      cwd,\n      reject: false,\n      timeout: 300_000, // 5 minute timeout\n    });\n\n    return {\n      stdout: result.stdout,\n      stderr: result.stderr,\n      exitCode: result.exitCode ?? (result.signal ? 1 : 0),\n    };\n  } catch (error) {\n    const message = error instanceof Error ? error.message : \"Unknown error\";\n    return {\n      stdout: \"\",\n      stderr: message,\n      exitCode: 1,\n    };\n  }\n}\n\nexport async function checkPythonAvailable(): Promise<boolean> {\n  try {\n    const result = await execa(\"uv\", [\"run\", \"python\", \"--version\"], { reject: false });\n    return result.exitCode === 0;\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";AAAA,SAAS,aAAa;AActB,eAAsB,gBAAgB,SAA2D;AAC/F,QAAM,EAAE,QAAQ,OAAO,CAAC,GAAG,IAAI,IAAI;AAEnC,MAAI;AACF,UAAM,SAAS,MAAM,MAAM,MAAM,CAAC,OAAO,UAAU,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG;AAAA,MAC/E;AAAA,MACA,QAAQ;AAAA,MACR,SAAS;AAAA;AAAA,IACX,CAAC;AAED,WAAO;AAAA,MACL,QAAQ,OAAO;AAAA,MACf,QAAQ,OAAO;AAAA,MACf,UAAU,OAAO,aAAa,OAAO,SAAS,IAAI;AAAA,IACpD;AAAA,EACF,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU;AACzD,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,UAAU;AAAA,IACZ;AAAA,EACF;AACF;AAEA,eAAsB,uBAAyC;AAC7D,MAAI;AACF,UAAM,SAAS,MAAM,MAAM,MAAM,CAAC,OAAO,UAAU,WAAW,GAAG,EAAE,QAAQ,MAAM,CAAC;AAClF,WAAO,OAAO,aAAa;AAAA,EAC7B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rag-forge/shared",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Internal shared utilities for RAG-Forge packages",
   "author": "Femi Adedayo",
   "repository": {
@@ -12,7 +12,11 @@
   "bugs": {
     "url": "https://github.com/hallengray/rag-forge/issues"
   },
-  "keywords": ["rag", "rag-forge", "internal"],
+  "keywords": [
+    "rag",
+    "rag-forge",
+    "internal"
+  ],
   "type": "module",
   "exports": {
     ".": {
@@ -20,11 +24,10 @@
       "types": "./dist/python-bridge.d.ts"
     }
   },
-  "files": ["dist"],
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit"
-  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "dependencies": {
     "execa": "^9.0.0"
   },
@@ -36,5 +39,9 @@
   "engines": {
     "node": ">=20.0.0"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}