graphjin 3.11.3 → 3.13.0

package/README.md

@@ -61,6 +61,7 @@ GraphJin started
   Web UI:      http://localhost:8080/
   GraphQL:     http://localhost:8080/api/v1/graphql
   REST API:    http://localhost:8080/api/v1/rest/
+  Workflows:   http://localhost:8080/api/v1/workflows/<name>
   MCP:         http://localhost:8080/api/v1/mcp
 
 Claude Desktop Configuration
@@ -89,7 +90,7 @@ Copy the JSON config shown and add it to your Claude Desktop config file (see be
 GraphJin includes a guided installer that configures MCP for OpenAI Codex, Claude Code, or both.
 
 ```bash
-# Guided mode (asks target client, scope, and mode)
+# Guided mode (asks target client and scope)
 graphjin mcp install
 ```
 
@@ -109,15 +110,12 @@ graphjin mcp install --client codex --scope project --yes
 graphjin mcp install --client claude --scope project --yes
 ```
 
-Backwards compatibility alias:
-
-```bash
-graphjin mcp plugin install
-```
-
 #### Troubleshooting
 
-- `graphjin mcp install` uses your `--path` value for stdio mode (`graphjin mcp --path <config-path>`).
+- `graphjin mcp install` defaults to `--server http://localhost:8080/`.
+- Set a custom server URL with `--server`, for example:
+  - `graphjin mcp install --client codex --server http://my-host:8080/ --yes`
+- Claude installs use `graphjin mcp --server <url>` under the hood.
 - If Codex CLI does not support `codex mcp add --scope` (older versions), GraphJin automatically falls back to updating:
   - global scope: `~/.codex/config.toml`
   - local scope: `.codex/config.toml`
@@ -155,7 +153,8 @@ Copy paste the Claude Desktop Config provided by `graphjin serve` into the Claud
 1. **Connects to database** - Reads your schema automatically
 2. **Discovers relationships** - Foreign keys become navigable joins
 3. **Exposes MCP tools** - Teach any LLM the query syntax
-4. **Compiles to SQL** - Every request becomes a single optimized query
+4. **Runs JS workflows** - Chain multiple GraphJin MCP tools in one reusable workflow
+5. **Compiles to SQL** - Every request becomes a single optimized query
 
 No resolvers. No ORM. No N+1 queries. Just point and query.
 
@@ -221,7 +220,45 @@ Works from Node.js, Go, or any WebSocket client.
 
 ## MCP Tools
 
-GraphJin exposes several tools that guide AI models to write valid queries. Key tools: `list_tables` and `describe_table` for schema discovery, `get_query_syntax` for learning the DSL, `execute_graphql` for running queries, and `execute_saved_query` for production-approved queries. Prompts like `write_query` and `fix_query_error` help models construct and debug queries.
+GraphJin exposes several tools that guide AI models to write valid queries. Key tools: `list_tables` and `describe_table` for schema discovery, `get_query_syntax` for learning the DSL, `execute_graphql` for running queries, and `execute_saved_query` for production-approved queries.
+
+For JS orchestration, use:
+- `get_js_runtime_api` to discover exactly which globals/functions are available inside workflow scripts
+- `execute_workflow` to run `./workflows/<name>.js` with input variables
+
+Prompts like `write_query` and `fix_query_error` help models construct and debug queries.
+
+## JS Workflows (MCP + REST)
+
+Workflows let an LLM run multi-step logic in JavaScript while still using GraphJin MCP tools for DB-aware operations.
+
+Create a file in `./workflows`, for example `./workflows/customer_insights.js`:
+
+```js
+function main(input) {
+  const tables = gj.tools.listTables({});
+  const top = gj.tools.executeSavedQuery({
+    name: "top_customers",
+    variables: { limit: input.limit || 5 }
+  });
+  return { tables, top };
+}
+```
+
+### Run via MCP
+
+Call:
+- `get_js_runtime_api` first (for exact runtime schema)
+- `execute_workflow` with:
+  - `name`: workflow file name (with or without `.js`)
+  - `variables`: input payload passed to global `input` and `main(input)`
+
+### Run via REST
+
+- `POST /api/v1/workflows/<name>` with JSON body
+- `GET /api/v1/workflows/<name>?variables={...json...}`
+
+Both map variables to the same workflow input object.
 
 ## Chat Walkthroughs
 

package/bin/graphjin.js

@@ -1,10 +1,17 @@
 #!/usr/bin/env node
 const { spawn } = require('child_process');
 const path = require('path');
+const fs = require('fs');
 
 const ext = process.platform === 'win32' ? '.exe' : '';
 const binary = path.join(__dirname, 'graphjin' + ext);
 
+if (!fs.existsSync(binary)) {
+  console.error(`GraphJin binary not found at: ${binary}`);
+  console.error('Try reinstalling: npm install -g graphjin');
+  process.exit(1);
+}
+
 const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
 
 child.on('error', (err) => {
@@ -13,4 +20,10 @@ child.on('error', (err) => {
   process.exit(1);
 });
 
-child.on('exit', (code) => process.exit(code || 0));
+child.on('exit', (code, signal) => {
+  if (signal) {
+    console.error(`graphjin terminated by signal: ${signal}`);
+    process.exit(1);
+  }
+  process.exit(code ?? 0);
+});

package/bin/install.js

@@ -39,6 +39,29 @@ async function download(url, dest) {
   });
 }
 
+async function downloadWithFallback(candidates, binDir) {
+  let lastErr;
+
+  for (const candidate of candidates) {
+    const archivePath = path.join(binDir, candidate.filename);
+
+    try {
+      await download(candidate.url, archivePath);
+      return {
+        archivePath,
+        filename: candidate.filename,
+      };
+    } catch (err) {
+      lastErr = err;
+      try {
+        fs.unlinkSync(archivePath);
+      } catch {}
+    }
+  }
+
+  throw lastErr || new Error('No download candidates available');
+}
+
 async function extract(tarPath, destDir) {
   // Use tar module for extraction
   const tar = require('tar');
@@ -62,14 +85,28 @@ async function install() {
     process.exit(1);
   }
 
-  const ext = platform === 'windows' ? '.zip' : '.tar.gz';
-  const filename = `graphjin_${platform}_${arch}${ext}`;
-  const url = `https://github.com/dosco/graphjin/releases/download/v${version}/${filename}`;
-
   const binDir = __dirname;
-  const archivePath = path.join(binDir, filename);
   const binaryName = platform === 'windows' ? 'graphjin.exe' : 'graphjin';
   const binaryPath = path.join(binDir, binaryName);
+  const releaseBase = `https://github.com/dosco/graphjin/releases/download/v${version}`;
+
+  // New releases include version in the archive name. Keep legacy fallback
+  // names to remain backward compatible with older tags.
+  const filenames = platform === 'windows'
+    ? [
+        `graphjin_${version}_${platform}_${arch}.tar.gz`,
+        `graphjin_${version}_${platform}_${arch}.zip`,
+        `graphjin_${platform}_${arch}.tar.gz`,
+        `graphjin_${platform}_${arch}.zip`,
+      ]
+    : [
+        `graphjin_${version}_${platform}_${arch}.tar.gz`,
+        `graphjin_${platform}_${arch}.tar.gz`,
+      ];
+  const candidates = filenames.map((filename) => ({
+    filename,
+    url: `${releaseBase}/${filename}`,
+  }));
 
   // Skip if binary already exists
   if (fs.existsSync(binaryPath)) {
@@ -79,12 +116,17 @@ async function install() {
 
   console.log(`Downloading GraphJin v${version} for ${platform}/${arch}...`);
 
+  let archivePath = '';
+  let selectedFilename = '';
+
   try {
-    await download(url, archivePath);
+    const selected = await downloadWithFallback(candidates, binDir);
+    archivePath = selected.archivePath;
+    selectedFilename = selected.filename;
 
     console.log('Extracting...');
 
-    if (platform === 'windows') {
+    if (platform === 'windows' && selectedFilename.endsWith('.zip')) {
       // For Windows, use PowerShell to extract
       execSync(`powershell -command "Expand-Archive -Path '${archivePath}' -DestinationPath '${binDir}' -Force"`, {
         stdio: 'inherit',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphjin",
-  "version": "3.11.3",
+  "version": "3.13.0",
   "description": "GraphJin CLI - Build APIs in 5 minutes with GraphQL",
   "bin": {
     "graphjin": "bin/graphjin.js"