@kaluchi/jdtbridge 1.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @kaluchi/jdtbridge — CLI reference
+
+CLI for [JDT Bridge](../README.md). Requires Eclipse running with the jdtbridge plugin installed.
+
+## Install
+
+```bash
+cd cli
+npm install
+npm link    # registers `jdt` and `jdtbridge` global commands
+```
+
+## Plugin setup
+
+```bash
+jdt setup                       # build + install into Eclipse
+jdt setup --check               # diagnostic: show status of all components
+jdt setup --skip-build          # reinstall last build
+jdt setup --clean               # clean build (mvn clean verify)
+jdt setup --remove              # uninstall plugin from Eclipse
+jdt setup --eclipse <path>      # specify Eclipse path (saved to config)
+```
+
+If Eclipse is running, you will be prompted to stop it. After install, Eclipse restarts automatically with the same workspace.
+
+## Commands
+
+Run `jdt help <command>` for detailed flags and examples. Most commands have short aliases.
+
+### Search & navigation
+
+```bash
+jdt projects                                           # list workspace projects
+jdt project-info <name> [--lines N]                    # (alias: pi) project overview
+jdt find <Name> [--source-only]                        # find type declarations (* wildcards)
+jdt references <FQN> [method] [--field <name>]         # (alias: refs) references to type/method/field
+jdt subtypes <FQN>                                     # (alias: subt) all subtypes/implementors
+jdt hierarchy <FQN>                                    # (alias: hier) supers + interfaces + subtypes
+jdt implementors <FQN> <method> [--arity N]            # (alias: impl) implementations of interface method
+jdt type-info <FQN>                                    # (alias: ti) class overview (fields, methods)
+jdt source <FQN> [method] [--arity N]                  # (alias: src) source code (project + libraries)
+```
+
+### Testing & building
+
+```bash
+jdt build [--project <name>] [--clean]                 # (alias: b) build project
+jdt test <FQN> [method] [--timeout N]                  # run JUnit test class or method
+jdt test --project <name> [--package <pkg>]            # run tests in project/package
+```
+
+All commands auto-refresh from disk. `build` is the only command that triggers explicit builds.
+
+### Diagnostics
+
+```bash
+jdt errors [--project <name>] [--file <path>]          # (alias: err) compilation errors
+jdt errors --warnings --all                            # include warnings and all marker types
+```
+
+File paths are workspace-relative: `my-app/src/main/java/.../Foo.java`.
+
+### Refactoring
+
+```bash
+jdt organize-imports <file>                            # (alias: oi) organize imports
+jdt format <file>                                      # (alias: fmt) format code (Eclipse settings)
+jdt rename <FQN> <newName>                             # rename type
+jdt rename <FQN> <newName> --method <old>              # rename method
+jdt rename <FQN> <newName> --field <old>               # rename field
+jdt move <FQN> <target.package>                        # move type to another package
+```
+
+### Editor
+
+```bash
+jdt active-editor                                      # (alias: ae) current file and cursor line
+jdt open <FQN> [method] [--arity N]                    # open in Eclipse editor
+```
+
+## Instance discovery
+
+The CLI reads `~/.jdtbridge/instances/*.json` to find running Eclipse instances. Each file contains port, auth token, PID, and workspace path. Stale instances are filtered by PID liveness.
+
+When multiple instances are running, use `--workspace <hint>` or the CLI picks the first live one.
+
+Override the home directory with `JDTBRIDGE_HOME` environment variable.
+
+## Color output
+
+Auto-detected from TTY. Override:
+
+- `--color` / `--no-color` flags
+- `FORCE_COLOR=1` / `NO_COLOR=1` env
+- `JDTBRIDGE_COLOR=1` env
+
+## Development
+
+```bash
+npm test              # run tests
+npm run test:watch    # watch mode
+```

package/bin/jdt.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.mjs";
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@kaluchi/jdtbridge",
+  "version": "1.1.0",
+  "description": "CLI for Eclipse JDT Bridge — semantic Java analysis via Eclipse JDT SearchEngine",
+  "type": "module",
+  "bin": {
+    "jdt": "./bin/jdt.mjs",
+    "jdtbridge": "./bin/jdt.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "eclipse",
+    "jdt",
+    "java",
+    "refactoring",
+    "search"
+  ],
+  "license": "Apache-2.0",
+  "author": "kaluchi",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kaluchi/jdtbridge.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/kaluchi/jdtbridge/tree/master/cli",
+  "bugs": "https://github.com/kaluchi/jdtbridge/issues",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.2.4",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.0"
+  }
+}

package/src/args.mjs

@@ -0,0 +1,37 @@
+// CLI argument parsing utilities.
+
+/**
+ * Parse --flag and --key value pairs from args array.
+ * Boolean flags (standalone --flag) get value `true`.
+ * Key-value pairs (--key value) get the string value.
+ */
+export function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--")) {
+      const key = args[i].slice(2);
+      if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+        flags[key] = args[++i];
+      } else {
+        flags[key] = true;
+      }
+    }
+  }
+  return flags;
+}
+
+/**
+ * Extract positional arguments (non-flag values) from args array.
+ * Skips --flag and --key value pairs.
+ */
+export function extractPositional(args) {
+  const result = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--")) {
+      if (i + 1 < args.length && !args[i + 1].startsWith("--")) i++;
+    } else {
+      result.push(args[i]);
+    }
+  }
+  return result;
+}

package/src/cli.mjs

@@ -0,0 +1,174 @@
+// Main CLI dispatcher.
+// Maps command names to handler functions and provides help.
+
+import { projects, help as projectsHelp } from "./commands/projects.mjs";
+import { projectInfo, help as projectInfoHelp } from "./commands/project-info.mjs";
+import { find, help as findHelp } from "./commands/find.mjs";
+import { references, help as referencesHelp } from "./commands/references.mjs";
+import { subtypes, help as subtypesHelp } from "./commands/subtypes.mjs";
+import { hierarchy, help as hierarchyHelp } from "./commands/hierarchy.mjs";
+import { implementors, help as implementorsHelp } from "./commands/implementors.mjs";
+import { typeInfo, help as typeInfoHelp } from "./commands/type-info.mjs";
+import { source, help as sourceHelp } from "./commands/source.mjs";
+import { build, help as buildHelp } from "./commands/build.mjs";
+import { test, help as testHelp } from "./commands/test.mjs";
+import { errors, help as errorsHelp } from "./commands/errors.mjs";
+import {
+  organizeImports,
+  format,
+  rename,
+  move,
+  organizeImportsHelp,
+  formatHelp,
+  renameHelp,
+  moveHelp,
+} from "./commands/refactoring.mjs";
+import {
+  activeEditor,
+  open,
+  activeEditorHelp,
+  openHelp,
+} from "./commands/editor.mjs";
+import { setup, help as setupHelp } from "./commands/setup.mjs";
+import { isConnectionError } from "./client.mjs";
+import { bold, red, dim } from "./color.mjs";
+
+const commands = {
+  projects: { fn: projects, help: projectsHelp },
+  "project-info": { fn: projectInfo, help: projectInfoHelp },
+  find: { fn: find, help: findHelp },
+  references: { fn: references, help: referencesHelp },
+  subtypes: { fn: subtypes, help: subtypesHelp },
+  hierarchy: { fn: hierarchy, help: hierarchyHelp },
+  implementors: { fn: implementors, help: implementorsHelp },
+  "type-info": { fn: typeInfo, help: typeInfoHelp },
+  source: { fn: source, help: sourceHelp },
+  build: { fn: build, help: buildHelp },
+  test: { fn: test, help: testHelp },
+  errors: { fn: errors, help: errorsHelp },
+  "organize-imports": { fn: organizeImports, help: organizeImportsHelp },
+  format: { fn: format, help: formatHelp },
+  rename: { fn: rename, help: renameHelp },
+  move: { fn: move, help: moveHelp },
+  "active-editor": { fn: activeEditor, help: activeEditorHelp },
+  open: { fn: open, help: openHelp },
+  setup: { fn: setup, help: setupHelp },
+};
+
+/** Short aliases for frequently used commands. */
+const aliases = {
+  refs: "references",
+  impl: "implementors",
+  subt: "subtypes",
+  hier: "hierarchy",
+  pi: "project-info",
+  ti: "type-info",
+  oi: "organize-imports",
+  ae: "active-editor",
+  src: "source",
+  b: "build",
+  err: "errors",
+  fmt: "format",
+};
+
+// Reverse map: command name → list of its aliases (for display).
+const aliasesOf = {};
+for (const [short, full] of Object.entries(aliases)) {
+  (aliasesOf[full] ||= []).push(short);
+}
+
+/** Resolve a command name or alias to its full name. */
+function resolve(name) {
+  if (commands[name]) return name;
+  return aliases[name] || null;
+}
+
+function fmtAliases(name) {
+  const list = aliasesOf[name];
+  return list ? " " + dim("(" + list.join(", ") + ")") : "";
+}
+
+function printOverview() {
+  console.log(`Eclipse JDT Bridge — semantic Java analysis via Eclipse JDT SearchEngine.
+Requires: Eclipse running with the jdtbridge plugin.
+
+Search & navigation:
+  projects                                    list workspace projects
+  project-info${fmtAliases("project-info")} <name> [--lines N]             project overview (adaptive detail)
+  find <Name|*Pattern*> [--source-only]       find type declarations
+  references${fmtAliases("references")} <FQN> [method] [--field <name>]  references to type/method/field
+  subtypes${fmtAliases("subtypes")} <FQN>                              all subtypes/implementors
+  hierarchy${fmtAliases("hierarchy")} <FQN>                             full hierarchy (supers + interfaces + subtypes)
+  implementors${fmtAliases("implementors")} <FQN> <method> [--arity n]     implementations of interface method
+  type-info${fmtAliases("type-info")} <FQN>                             class overview (fields, methods, line numbers)
+  source${fmtAliases("source")} <FQN> [method] [--arity n]           type or method source code (project and libraries)
+
+Testing & building:
+  build${fmtAliases("build")} [--project <name>] [--clean]      build project (incremental or clean)
+  test <FQN> [method]                         run JUnit test class or method
+  test --project <name> [--package <pkg>]     run tests in project/package
+
+Diagnostics:
+  errors${fmtAliases("errors")} [--file <path>] [--project <name>]   compilation errors
+
+Refactoring:
+  organize-imports${fmtAliases("organize-imports")} <file>                     organize imports
+  format${fmtAliases("format")} <file>                               format with Eclipse project settings
+  rename <FQN> <newName> [--method|--field]   rename type/method/field
+  move <FQN> <target.package>                 move type to another package
+
+Editor:
+  active-editor${fmtAliases("active-editor")}                               current file and cursor line
+  open <FQN> [method]                         open in Eclipse editor
+
+Setup:
+  setup [--check|--remove]                    install/check/remove Eclipse plugin
+
+Use "jdt help <command>" for detailed usage of any command.`);
+}
+
+export async function run(argv) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === "--help") {
+    printOverview();
+    return;
+  }
+
+  if (command === "help") {
+    const topic = rest[0];
+    const resolved = topic ? resolve(topic) : null;
+    if (resolved) {
+      console.log(commands[resolved].help);
+    } else if (topic) {
+      console.error(`Unknown command: ${topic}`);
+      console.log();
+      printOverview();
+    } else {
+      printOverview();
+    }
+    return;
+  }
+
+  const resolved = resolve(command);
+  if (!resolved) {
+    console.error(`Unknown command: ${command}`);
+    console.log();
+    printOverview();
+    process.exit(1);
+  }
+
+  try {
+    await commands[resolved].fn(rest);
+  } catch (e) {
+    if (isConnectionError(e)) {
+      console.error(
+        bold(red("Eclipse JDT Bridge not responding.")) +
+          "\nCheck that Eclipse is running with the jdtbridge plugin.\n",
+      );
+    } else {
+      console.error(e.message);
+    }
+    process.exit(1);
+  }
+}

package/src/client.mjs

@@ -0,0 +1,168 @@
+// HTTP client for JDT Bridge server.
+
+import { request } from "node:http";
+import { findInstance } from "./discovery.mjs";
+import { red, bold } from "./color.mjs";
+
+/** @type {import('./discovery.mjs').Instance|null} */
+let _instance;
+
+/**
+ * Ensure we have a connected instance. Call before any HTTP request.
+ * @param {string} [workspaceHint]
+ * @returns {import('./discovery.mjs').Instance}
+ */
+export function connect(workspaceHint) {
+  if (_instance) return _instance;
+  _instance = findInstance(workspaceHint);
+  if (!_instance) {
+    console.error(
+      bold(red("Eclipse JDT Bridge not running.")) +
+        "\n\nNo live instances found. Check that:" +
+        "\n  1. Eclipse is running" +
+        "\n  2. The jdtbridge plugin is installed (io.github.kaluchi.jdtbridge)" +
+        "\n  3. Instance files exist in ~/.jdtbridge/instances/",
+    );
+    process.exit(1);
+  }
+  return _instance;
+}
+
+/** Reset cached instance (for testing). */
+export function resetClient() {
+  _instance = null;
+}
+
+function authHeaders() {
+  const inst = _instance;
+  return inst && inst.token
+    ? { Authorization: `Bearer ${inst.token}` }
+    : {};
+}
+
+/**
+ * Parse JSON responses, tolerating non-finite numeric literals sometimes
+ * returned by the Eclipse bridge (for example `time: NaN` in test results).
+ * @param {string} data
+ * @returns {any}
+ */
+function parseJson(data) {
+  try {
+    return JSON.parse(data);
+  } catch {
+    const sanitized = data
+      .replace(/:\s*NaN\b/g, ": null")
+      .replace(/:\s*Infinity\b/g, ": null")
+      .replace(/:\s*-Infinity\b/g, ": null");
+    if (sanitized !== data) {
+      return JSON.parse(sanitized);
+    }
+    throw new Error("Invalid JSON: " + data);
+  }
+}
+
+/**
+ * HTTP GET request, returns parsed JSON.
+ * @param {string} path - URL path with query string
+ * @param {number} [timeoutMs=10000]
+ * @returns {Promise<any>}
+ */
+export function get(path, timeoutMs = 10_000) {
+  const inst = connect();
+  return new Promise((resolve, reject) => {
+    const req = request(
+      {
+        hostname: "127.0.0.1",
+        port: inst.port,
+        path,
+        method: "GET",
+        timeout: timeoutMs,
+        headers: authHeaders(),
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+            return;
+          }
+          try {
+            resolve(parseJson(data));
+          } catch (e) {
+            reject(e);
+          }
+        });
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error("Request timed out"));
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+/**
+ * HTTP GET request, returns raw response with headers.
+ * Used for /source which returns text/plain.
+ * @param {string} path
+ * @param {number} [timeoutMs=10000]
+ * @returns {Promise<{headers: object, body: string}>}
+ */
+export function getRaw(path, timeoutMs = 10_000) {
+  const inst = connect();
+  return new Promise((resolve, reject) => {
+    const req = request(
+      {
+        hostname: "127.0.0.1",
+        port: inst.port,
+        path,
+        method: "GET",
+        timeout: timeoutMs,
+        headers: authHeaders(),
+      },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+            return;
+          }
+          const contentType = res.headers["content-type"] || "";
+          if (contentType.startsWith("application/json")) {
+            try {
+              const json = parseJson(data);
+              if (json.error) {
+                reject(new Error(json.error));
+              } else {
+                resolve({ headers: res.headers, body: data });
+              }
+            } catch (e) {
+              reject(e);
+            }
+          } else {
+            resolve({ headers: res.headers, body: data });
+          }
+        });
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error("Request timed out"));
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+
+/**
+ * Check if error is a connection refused error.
+ * @param {Error} e
+ * @returns {boolean}
+ */
+export function isConnectionError(e) {
+  return e.code === "ECONNREFUSED" || e.code === "ECONNRESET";
+}

package/src/color.mjs

@@ -0,0 +1,40 @@
+// Colored output with TTY auto-detection.
+// Enable: --color flag, JDTBRIDGE_COLOR=1, or FORCE_COLOR=1
+// Disable: --no-color flag, NO_COLOR=1
+
+import pc from "picocolors";
+
+let _enabled;
+
+/** Check if color output is enabled. */
+export function isColorEnabled() {
+  if (_enabled !== undefined) return _enabled;
+
+  if (process.env.NO_COLOR || process.argv.includes("--no-color")) {
+    _enabled = false;
+  } else if (
+    process.env.FORCE_COLOR ||
+    process.env.JDTBRIDGE_COLOR ||
+    process.argv.includes("--color")
+  ) {
+    _enabled = true;
+  } else {
+    _enabled = process.stdout.isTTY === true;
+  }
+  return _enabled;
+}
+
+/** Set color enabled/disabled explicitly. */
+export function setColorEnabled(enabled) {
+  _enabled = enabled;
+}
+
+function wrap(fn) {
+  return (s) => (isColorEnabled() ? fn(s) : s);
+}
+
+export const red = wrap(pc.red);
+export const green = wrap(pc.green);
+export const yellow = wrap(pc.yellow);
+export const bold = wrap(pc.bold);
+export const dim = wrap(pc.dim);

package/src/commands/build.mjs

@@ -0,0 +1,40 @@
+import { get } from "../client.mjs";
+import { parseFlags } from "../args.mjs";
+
+export async function build(args) {
+  const flags = parseFlags(args);
+  const params = [];
+  if (flags.project) params.push(`project=${encodeURIComponent(flags.project)}`);
+  if (flags.clean) params.push("clean");
+
+  let url = "/build";
+  if (params.length > 0) url += "?" + params.join("&");
+  const result = await get(url, 180_000);
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+  const n = result.errors || 0;
+  if (n === 0) {
+    console.log("Build complete (0 errors)");
+  } else {
+    console.log(`Build complete (${n} errors)`);
+    process.exit(1);
+  }
+}
+
+export const help = `Build a project via Eclipse incremental or clean builder.
+
+Usage:  jdt build [--project <name>] [--clean]
+
+Options:
+  --project <name>   project to build (omit for workspace-wide incremental)
+  --clean            clean + full rebuild (requires --project)
+
+Always refreshes from disk before building.
+Exit code: 0 if no compilation errors, 1 if errors found.
+
+Examples:
+  jdt build --project m8-client
+  jdt build --project m8-client --clean
+  jdt build --project m8-client --clean && jdt test --project m8-client-gwt`;

package/src/commands/editor.mjs

@@ -0,0 +1,49 @@
+import { get } from "../client.mjs";
+import { extractPositional, parseFlags } from "../args.mjs";
+import { stripProject } from "../paths.mjs";
+
+export async function activeEditor() {
+  const result = await get("/active-editor");
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+  if (result.file === null) {
+    console.log("(no file open)");
+  } else {
+    console.log(`${stripProject(result.file)}:${result.line}`);
+  }
+}
+
+export async function open(args) {
+  const pos = extractPositional(args);
+  const flags = parseFlags(args);
+  const fqn = pos[0];
+  const method = pos[1];
+  if (!fqn) {
+    console.error("Usage: open <FQN> [method] [--arity n]");
+    process.exit(1);
+  }
+  let url = `/open?class=${encodeURIComponent(fqn)}`;
+  if (method) url += `&method=${encodeURIComponent(method)}`;
+  if (flags.arity !== undefined && flags.arity !== true)
+    url += `&arity=${flags.arity}`;
+  const result = await get(url);
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+  console.log("Opened");
+}
+
+export const activeEditorHelp = `Show the file and cursor line of the active Eclipse editor.
+
+Usage:  jdt active-editor`;
+
+export const openHelp = `Open a type or method in the Eclipse editor.
+
+Usage:  jdt open <FQN> [method] [--arity n]
+
+Examples:
+  jdt open app.m8.dao.StaffDaoImpl
+  jdt open app.m8.dao.StaffDaoImpl getStaff`;