@kaluchi/jdtbridge 1.4.0 → 1.6.0

package/README.md

@@ -45,8 +45,10 @@ jdt source <FQMN>                                      # (alias: src) source cod
 
 ```bash
 jdt build [--project <name>] [--clean]                 # (alias: b) build project
-jdt test <FQMN> [--timeout N]                           # run JUnit test class or method
-jdt test --project <name> [--package <pkg>]            # run tests in project/package
+jdt test run <FQN> [-f] [-q]                            # launch tests (non-blocking)
+jdt test run --project <name> [-f]                     # run tests in project
+jdt test status <session> [-f] [--all] [--ignored]     # show test progress/results
+jdt test sessions                                       # list test sessions
 ```
 
 All commands auto-refresh from disk. `build` is the only command that triggers explicit builds.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaluchi/jdtbridge",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "CLI for Eclipse JDT Bridge — semantic Java analysis via Eclipse JDT SearchEngine",
   "type": "module",
   "bin": {

package/src/args.mjs

@@ -103,5 +103,17 @@ function splitParams(str) {
   }
   const last = str.substring(start).trim();
   if (last) params.push(last);
-  return params;
+  return params.map(eraseGenerics);
+}
+
+/** Strip generics: Map<String,Integer> → Map, List<String>[] → List[] */
+function eraseGenerics(type) {
+  let result = "";
+  let depth = 0;
+  for (const ch of type) {
+    if (ch === "<") depth++;
+    else if (ch === ">") depth--;
+    else if (depth === 0) result += ch;
+  }
+  return result;
 }

package/src/claude-setup.mjs

@@ -0,0 +1,83 @@
+// Configure Claude Code for JDT Bridge projects.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+const JDT_HOOK_COMMAND = `node -e "d=JSON.parse(require('fs').readFileSync(0,'utf8'));d.tool_input?.command?.startsWith('jdt ')&&process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow'}}))"`;
+
+/**
+ * Find the project root (git root or cwd).
+ * @returns {string}
+ */
+export function findProjectRoot() {
+  try {
+    return execSync("git rev-parse --show-toplevel", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+/**
+ * Merge JDT Bridge settings into a Claude Code settings object.
+ * Idempotent — safe to call multiple times.
+ * @param {object} settings existing settings (mutated in place)
+ * @returns {object} the mutated settings
+ */
+export function mergeJdtSettings(settings) {
+  // Permissions
+  if (!settings.permissions) settings.permissions = {};
+  const allow = settings.permissions.allow || [];
+  if (!allow.includes("Bash(jdt *)")) allow.push("Bash(jdt *)");
+  settings.permissions.allow = allow;
+
+  // Hook
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+  const existing = settings.hooks.PreToolUse.find(
+    (h) =>
+      h.matcher === "Bash" &&
+      h.hooks?.some((hk) => hk.command === JDT_HOOK_COMMAND),
+  );
+  if (!existing) {
+    settings.hooks.PreToolUse.push({
+      matcher: "Bash",
+      hooks: [{ type: "command", command: JDT_HOOK_COMMAND }],
+    });
+  }
+
+  return settings;
+}
+
+/**
+ * Write Claude Code settings for JDT Bridge to a project.
+ * Creates .claude/settings.json if it doesn't exist,
+ * merges into existing if it does.
+ * @param {string} [root] project root (default: git root or cwd)
+ * @returns {{ file: string, settings: object }}
+ */
+export function installClaudeSettings(root) {
+  if (!root) root = findProjectRoot();
+
+  const dir = join(root, ".claude");
+  const file = join(dir, "settings.json");
+
+  let settings = {};
+  if (existsSync(file)) {
+    try {
+      settings = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      // corrupt — overwrite
+    }
+  }
+
+  mergeJdtSettings(settings);
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
+
+  return { file, settings };
+}

package/src/cli.mjs

@@ -11,7 +11,9 @@ import { implementors, help as implementorsHelp } from "./commands/implementors.
 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 { testRun, help as testRunHelp } from "./commands/test-run.mjs";
+import { testStatus, help as testStatusHelp } from "./commands/test-status.mjs";
+import { testSessions, help as testSessionsHelp } from "./commands/test-sessions.mjs";
 import { errors, help as errorsHelp } from "./commands/errors.mjs";
 import {
   organizeImports,
@@ -93,6 +95,36 @@ async function launchDispatch(args) {
   await cmd.fn(rest);
 }
 
+const testSubcommands = {
+  run: { fn: testRun, help: testRunHelp },
+  status: { fn: testStatus, help: testStatusHelp },
+  sessions: { fn: testSessions, help: testSessionsHelp },
+};
+
+const testHelp = `Run and monitor JUnit tests via Eclipse's built-in runner.
+
+Subcommands:
+  jdt test run <FQN> [-f] [-q]                launch tests (non-blocking)
+  jdt test status <session> [-f] [--all]      show test progress/results
+  jdt test sessions                           list test sessions
+
+Use "jdt help test <subcommand>" for details.`;
+
+async function testDispatch(args) {
+  const [sub, ...rest] = args;
+  if (!sub || sub === "--help") {
+    console.log(testHelp);
+    return;
+  }
+  const cmd = testSubcommands[sub];
+  if (!cmd) {
+    console.error(`Unknown test subcommand: ${sub}`);
+    console.log(testHelp);
+    process.exit(1);
+  }
+  await cmd.fn(rest);
+}
+
 const commands = {
   projects: { fn: projects, help: projectsHelp },
   "project-info": { fn: projectInfo, help: projectInfoHelp },
@@ -104,7 +136,7 @@ const commands = {
   "type-info": { fn: typeInfo, help: typeInfoHelp },
   source: { fn: source, help: sourceHelp },
   build: { fn: build, help: buildHelp },
-  test: { fn: test, help: testHelp },
+  test: { fn: testDispatch, help: testHelp },
   errors: { fn: errors, help: errorsHelp },
   "organize-imports": { fn: organizeImports, help: organizeImportsHelp },
   format: { fn: format, help: formatHelp },
@@ -162,12 +194,13 @@ Search & navigation:
   hierarchy${fmtAliases("hierarchy")} <FQN>                             full hierarchy (supers + interfaces + subtypes)
   implementors${fmtAliases("implementors")} <FQMN>                            implementations of interface method
   type-info${fmtAliases("type-info")} <FQN>                             class overview (fields, methods, line numbers)
-  source${fmtAliases("source")} <FQMN>                              type or method source code (project and libraries)
+  source${fmtAliases("source")} <FQMN>                              source + resolved references (navigation)
 
 Testing & building:
   build${fmtAliases("build")} [--project <name>] [--clean]      build project (incremental or clean)
-  test <FQMN>                                 run JUnit test class or method
-  test --project <name> [--package <pkg>]     run tests in project/package
+  test run <FQN> [-f] [-q]                    launch tests (non-blocking)
+  test status <session> [-f] [--all]          show test progress/results
+  test sessions                               list test sessions
 
 Diagnostics:
   errors${fmtAliases("errors")} [--file <path>] [--project <name>]   compilation errors
@@ -215,6 +248,8 @@ export async function run(argv) {
     const resolved = topic ? resolve(topic) : null;
     if (resolved === "launch" && rest[1] && launchSubcommands[rest[1]]) {
       console.log(launchSubcommands[rest[1]].help);
+    } else if (resolved === "test" && rest[1] && testSubcommands[rest[1]]) {
+      console.log(testSubcommands[rest[1]].help);
     } else if (resolved) {
       console.log(commands[resolved].help);
     } else if (topic) {

package/src/client.mjs

@@ -196,6 +196,55 @@ export function getStream(path, dest) {
   });
 }
 
+/**
+ * HTTP GET streaming with line-by-line callback. Designed for
+ * JSONL (newline-delimited JSON) endpoints. Calls onLine for
+ * each complete line received.
+ * Resolves when the server closes the connection.
+ * @param {string} path
+ * @param {(line: string) => void} onLine
+ * @returns {Promise<void>}
+ */
+export function getStreamLines(path, onLine) {
+  const inst = connect();
+  return new Promise((resolve, reject) => {
+    const req = request(
+      {
+        hostname: "127.0.0.1",
+        port: inst.port,
+        path,
+        method: "GET",
+        timeout: 0,
+        headers: authHeaders(),
+      },
+      (res) => {
+        if (res.statusCode !== 200) {
+          let data = "";
+          res.on("data", (chunk) => (data += chunk));
+          res.on("end", () => reject(new Error(data.trim())));
+          return;
+        }
+        let buffer = "";
+        res.on("data", (chunk) => {
+          buffer += chunk;
+          const lines = buffer.split("\n");
+          buffer = lines.pop();
+          for (const line of lines) {
+            if (line.trim()) onLine(line);
+          }
+        });
+        res.on("end", () => {
+          if (buffer.trim()) onLine(buffer);
+          resolve();
+        });
+        res.on("error", reject);
+      },
+    );
+    req.on("error", reject);
+    req.end();
+  });
+}
+
 /**
  * Check if error is a connection refused error.
  * @param {Error} e

package/src/commands/editor.mjs

@@ -50,6 +50,6 @@ export const openHelp = `Open a type or method in the Eclipse editor.
 Usage:  jdt open <FQN>[#method[(param types)]]
 
 Examples:
-  jdt open app.m8.dao.StaffDaoImpl
-  jdt open app.m8.dao.StaffDaoImpl#getStaff
-  jdt open "app.m8.dao.StaffDaoImpl#save(Order)"`;
+  jdt open com.example.dao.UserDaoImpl
+  jdt open com.example.dao.UserDaoImpl#getStaff
+  jdt open "com.example.dao.UserDaoImpl#save(Order)"`;

package/src/commands/hierarchy.mjs

@@ -1,7 +1,6 @@
 import { get } from "../client.mjs";
 import { extractPositional } from "../args.mjs";
-import { stripProject } from "../paths.mjs";
-import { bold } from "../color.mjs";
+import { formatHierarchy } from "../format/hierarchy.mjs";
 
 export async function hierarchy(args) {
   const pos = extractPositional(args);
@@ -18,26 +17,16 @@ export async function hierarchy(args) {
     console.error(result.error);
     process.exit(1);
   }
-  if (result.supers.length > 0) {
-    console.log(bold("Superclasses:"));
-    for (const s of result.supers) {
-      const loc = s.binary ? "(binary)" : stripProject(s.file);
-      console.log(`  ${s.fqn}  ${loc}`);
-    }
-  }
-  if (result.interfaces.length > 0) {
-    console.log(bold("Interfaces:"));
-    for (const s of result.interfaces) {
-      const loc = s.binary ? "(binary)" : stripProject(s.file);
-      console.log(`  ${s.fqn}  ${loc}`);
-    }
-  }
-  if (result.subtypes.length > 0) {
-    console.log(bold("Subtypes:"));
-    for (const s of result.subtypes) {
-      const loc = s.binary ? "(binary)" : stripProject(s.file);
-      console.log(`  ${s.fqn}  ${loc}`);
-    }
+
+  const lines = [];
+  lines.push(`#### ${result.fqn || fqn}`);
+  lines.push("");
+  lines.push(...formatHierarchy(result));
+
+  if (lines.length > 2) {
+    console.log(lines.join("\n"));
+  } else {
+    console.log("No hierarchy found.");
   }
 }
 
@@ -45,4 +34,4 @@ export const help = `Show full type hierarchy: superclasses, interfaces, and sub
 
 Usage:  jdt hierarchy <FQN>
 
-Example:  jdt hierarchy app.m8.web.client.AGMEntryPoint`;
+Example:  jdt hierarchy com.example.client.AppEntryPoint`;

package/src/commands/implementors.mjs

@@ -35,4 +35,4 @@ export const help = `Find implementations of an interface method across all impl
 Usage:  jdt implementors <FQN>#<method>[(param types)]
 
 Examples:
-  jdt implementors app.m8.web.shared.core.HasId#getId`;
+  jdt implementors com.example.core.HasId#getId`;

package/src/commands/refactoring.mjs

@@ -109,11 +109,11 @@ Usage:  jdt rename <FQN>[#method[(param types)]] <newName>
         jdt rename <FQN> <newName> [--field <old>]
 
 Examples:
-  jdt rename app.m8.dto.Foo Bar
-  jdt rename app.m8.dto.Foo#getFoo getBar`;
+  jdt rename com.example.dto.Foo Bar
+  jdt rename com.example.dto.Foo#getFoo getBar`;
 
 export const moveHelp = `Move a type to another package (updates all references).
 
 Usage:  jdt move <FQN> <target.package>
 
-Example:  jdt move app.m8.dto.Foo app.m8.dto.shared`;
+Example:  jdt move com.example.dto.Foo com.example.dto.shared`;

package/src/commands/references.mjs

@@ -48,7 +48,7 @@ Flags:
   --field <name>   find references to a field
 
 Examples:
-  jdt references app.m8.dto.web.core.IdOrgRoot
-  jdt references app.m8.dao.StaffDaoImpl#getStaff
-  jdt references "app.m8.dao.StaffDaoImpl#save(Order)"
-  jdt references app.m8.dao.StaffDaoImpl --field staffCache`;
+  jdt references com.example.dto.BaseEntity
+  jdt references com.example.dao.UserDaoImpl#getStaff
+  jdt references "com.example.dao.UserDaoImpl#save(Order)"
+  jdt references com.example.dao.UserDaoImpl --field staffCache`;

package/src/commands/setup.mjs

@@ -357,11 +357,26 @@ export async function setup(args) {
     await runCheck(config);
   } else if (args.includes("--remove")) {
     await runRemove(config);
+  } else if (args.includes("--claude")) {
+    await setupClaude();
   } else {
     await runInstall(config, flags);
   }
 }
 
+async function setupClaude() {
+  const { installClaudeSettings } = await import("../claude-setup.mjs");
+  const { file } = installClaudeSettings();
+
+  console.log(`${green("✓")} Claude Code settings written to ${file}`);
+  console.log();
+  console.log("  Installed:");
+  console.log("  - Bash(jdt *) permission rule");
+  console.log("  - PreToolUse hook for # workaround (issue #34061)");
+  console.log();
+  console.log("  Restart Claude Code to apply.");
+}
+
 export const help = `Set up the Eclipse JDT Bridge plugin.
 
 Usage:  jdt setup [options]
@@ -370,6 +385,7 @@ Modes:
   (default)       build plugin from source, install into Eclipse
   --check         show status of all components (diagnostic only)
   --remove        uninstall the plugin from Eclipse
+  --claude        configure Claude Code for this project (permissions + hooks)
 
 Options:
   --eclipse <path>    Eclipse installation directory

package/src/commands/source.mjs

@@ -1,46 +1,306 @@
-import { getRaw } from "../client.mjs";
-import { extractPositional, parseFlags, parseFqmn } from "../args.mjs";
-import { stripProject } from "../paths.mjs";
+import { get } from "../client.mjs";
+import { extractPositional, parseFqmn } from "../args.mjs";
+import { formatHierEntry } from "../format/hierarchy.mjs";
 
 export async function source(args) {
-  const pos = extractPositional(args);
-  const flags = parseFlags(args);
-  const parsed = parseFqmn(pos[0]);
-  const fqn = parsed.className;
-  if (!fqn) {
-    console.error("Usage: source <FQN>[#method[(param types)]]");
+  const jsonFlag = args.includes("--json");
+  const pos = extractPositional(args).filter((a) => a !== "--json");
+  if (pos.length === 0) {
+    console.error("Usage: source <FQMN> [<FQMN> ...] [--json]");
     process.exit(1);
   }
-  const method = parsed.method || pos[1];
-  let url = `/source?class=${encodeURIComponent(fqn)}`;
-  if (method) url += `&method=${encodeURIComponent(method)}`;
+
+  const results = await Promise.all(pos.map((arg) => fetchOne(arg)));
+
+  if (jsonFlag) {
+    console.log(JSON.stringify(results.length === 1 ? results[0] : results, null, 2));
+    return;
+  }
+
+  const blocks = [];
+  for (const r of results) {
+    if (r.error) {
+      console.error(r.error);
+    } else if (Array.isArray(r)) {
+      blocks.push(...r.map(formatMarkdown));
+    } else {
+      blocks.push(formatMarkdown(r));
+    }
+  }
+  if (blocks.length === 0) process.exit(1);
+  console.log(blocks.join("\n\n---\n\n"));
+}
+
+async function fetchOne(fqmn) {
+  const parsed = parseFqmn(fqmn);
+  if (!parsed.className) return { error: `Invalid FQMN: ${fqmn}` };
+  let url = `/source?class=${encodeURIComponent(parsed.className)}`;
+  if (parsed.method) url += `&method=${encodeURIComponent(parsed.method)}`;
   if (parsed.paramTypes) {
     url += `&paramTypes=${encodeURIComponent(parsed.paramTypes.join(","))}`;
   }
-  const result = await getRaw(url, 30_000);
-  const file = result.headers["x-file"] || "?";
-  const startLine = result.headers["x-start-line"] || "?";
-  const endLine = result.headers["x-end-line"] || "?";
+  return get(url, 30_000);
+}
+
+// ---- Badge helpers ----
+
+const KIND_BADGE = {
+  method: "[M]",
+  field: "[F]",
+  constant: "[K]",
+  type: "[C]",
+};
+
+const TYPE_KIND_BADGE = {
+  class: "[C]",
+  interface: "[I]",
+  enum: "[E]",
+  annotation: "[A]",
+};
+
+function badge(ref) {
+  if (ref.kind === "type") return TYPE_KIND_BADGE[ref.typeKind] || "[C]";
+  return KIND_BADGE[ref.kind] || "[?]";
+}
+
+function returnTypeBadge(ref) {
+  if (ref.returnTypeKind) return TYPE_KIND_BADGE[ref.returnTypeKind] || "";
+  return "";
+}
+
+// ---- Ref formatting ----
+
+function formatMemberRef(ref) {
+  let line = `${badge(ref)} \`${ref.fqmn}\``;
+
+  // Return / field type
+  if (ref.type) {
+    const rtBadge = returnTypeBadge(ref);
+    const typeName = ref.returnTypeFqn || ref.type;
+    if (ref.isTypeVariable && ref.typeBound) {
+      line += ` → \`${ref.typeBound}\` (bound)`;
+    } else if (rtBadge) {
+      line += ` → ${rtBadge} \`${typeName}\``;
+    } else {
+      line += ` → \`${typeName}\``;
+    }
+  }
+
+  // Annotations
+  const annotations = [];
+  if (ref.static) annotations.push("static");
+  if (ref.inherited) annotations.push("inherited");
+  if (annotations.length > 0) line += ` (${annotations.join(", ")})`;
+
+  // Line number: server sends it but we don't render for incoming —
+  // callers are navigable by FQMN, line numbers just add noise
+
+  // Javadoc inline after —
+  if (ref.doc) line += ` — ${ref.doc}`;
+
+  return line;
+}
+
+function formatTypeHeader(ref) {
+  let line = `${badge(ref)} \`${ref.fqmn}\``;
+  if (ref.doc) line += ` — ${ref.doc}`;
+  return line;
+}
+
+// ---- Grouping ----
+
+function groupByDeclaringType(refs) {
+  const groups = [];
+  const groupMap = {};
+  for (const ref of refs) {
+    const typeFqn = ref.fqmn.split("#")[0];
+    if (!groupMap[typeFqn]) {
+      groupMap[typeFqn] = { typeRef: null, members: [] };
+      groups.push({ typeFqn, group: groupMap[typeFqn] });
+    }
+    if (!ref.fqmn.includes("#")) {
+      groupMap[typeFqn].typeRef = ref;
+    } else {
+      groupMap[typeFqn].members.push(ref);
+    }
+  }
+  return groups;
+}
 
-  if (startLine === "-1") {
-    // Multiple overloads: body has :startLine-endLine prefixes per block
-    console.log(
-      result.body.replace(
-        /^:(\d+-\d+)/gm,
-        `${stripProject(file)}:$1`,
-      ),
-    );
-  } else {
-    console.log(`${stripProject(file)}:${startLine}-${endLine}`);
-    console.log(result.body);
+function formatRefGroup({ typeFqn, group }, implIndex, viewScope) {
+  const lines = [];
+  // Type header: only show for standalone type refs (no members).
+  // When members exist, the type is already visible in their FQMNs.
+  const standalone = group.members.length === 0;
+  if (standalone && group.typeRef) {
+    lines.push(formatTypeHeader(group.typeRef));
+    // Show type implementations (domain-scoped)
+    const impls = implIndex[group.typeRef.fqmn];
+    if (impls && !(viewScope === "project" && group.typeRef.scope === "dependency")) {
+      for (const impl of impls) {
+        let implLine = `  ${badge(impl)} \`${impl.fqmn}\``;
+        if (impl.anonymous && impl.enclosingFqmn) {
+          implLine += ` — in \`${impl.enclosingFqmn}\``;
+        }
+        lines.push(implLine);
+      }
+    }
   }
+  for (const ref of group.members) {
+    lines.push(formatMemberRef(ref));
+    // Show implementations — skip dependency interface impls
+    // when viewing project source (domain scoping)
+    const impls = implIndex[ref.fqmn];
+    if (impls && !(viewScope === "project" && ref.scope === "dependency")) {
+      for (const impl of impls) {
+        lines.push(`  → ${badge(impl)} \`${impl.fqmn}\``);
+      }
+    }
+  }
+  return lines.join("\n");
 }
 
-export const help = `Print source code of a type or method.
+/** Build index: interfaceFqmn → [impl refs] */
+function buildImplIndex(refs) {
+  const index = {};
+  for (const ref of refs) {
+    if (ref.implementationOf) {
+      if (!index[ref.implementationOf]) index[ref.implementationOf] = [];
+      index[ref.implementationOf].push(ref);
+    }
+  }
+  return index;
+}
+
+
+// ---- Hierarchy (type-level) ----
+
+function formatHierarchySection(lines, result) {
+  const supers = result.supertypes || [];
+  const subs = result.subtypes || [];
+  if (supers.length > 0 || subs.length > 0) {
+    lines.push("");
+    lines.push("#### Hierarchy:");
+    for (const s of supers) {
+      lines.push(...formatHierEntry("↑", s));
+    }
+    for (const s of subs) {
+      lines.push(...formatHierEntry("", s));
+    }
+  }
+  if (result.enclosingType) {
+    lines.push("");
+    lines.push("#### Enclosing Type:");
+    const et = result.enclosingType;
+    const fqn = typeof et === "string" ? et : et.fqn;
+    const kind = typeof et === "string" ? "class" : (et.kind || "class");
+    lines.push(...formatHierEntry("", { fqn, kind, ...et }));
+  }
+}
+
+// ---- Markdown output ----
+
+function formatMarkdown(result) {
+  const lines = [];
+
+  // Header
+  const headerBadge = result.fqmn.includes("#") ? "[M]" : "[C]";
+  lines.push(`#### ${headerBadge} ${result.fqmn}`);
+  if (result.overrideTarget) {
+    const ot = result.overrideTarget;
+    // Support both object {fqmn, kind} and legacy string format
+    const fqmn = typeof ot === "string"
+      ? (ot.includes(" ") ? ot.split(" ", 2)[1] : ot)
+      : ot.fqmn;
+    lines.push(`overrides [M] \`${fqmn}\``);
+  }
+  lines.push(`\`${result.file}:${result.startLine}-${result.endLine}\``);
+  lines.push("");
+
+  // Source
+  lines.push("```java");
+  lines.push((result.source || "").trimEnd());
+  lines.push("```");
+
+  // Type-level: hierarchy instead of refs
+  if (result.supertypes || result.subtypes) {
+    formatHierarchySection(lines, result);
+    return lines.join("\n");
+  }
+
+  if (!result.refs || result.refs.length === 0) {
+    return lines.join("\n");
+  }
+
+  // Self-reference: the viewed member's declaring type
+  const selfFqn = result.fqmn.includes("#")
+    ? result.fqmn.split("#")[0] : null;
+
+  // Split by direction, filter self-reference type refs
+  const outgoing = result.refs.filter((r) =>
+    r.direction !== "incoming"
+    && !(r.kind === "type" && r.fqmn === selfFqn));
+  const incoming = result.refs.filter((r) => r.direction === "incoming");
+
+  const viewScope = result.viewScope;
+
+  // Implementations section (interface/abstract methods)
+  const impls = result.implementations || [];
+  if (impls.length > 0) {
+    lines.push("");
+    lines.push("#### Implementations:");
+    for (const impl of impls) {
+      let line = `[M] \`${impl.fqmn}\``;
+      if (impl.anonymous && impl.enclosingFqmn) {
+        line += ` — in \`${impl.enclosingFqmn}\``;
+      }
+      lines.push(line);
+    }
+  }
+
+  if (outgoing.length > 0) {
+    const implIndex = buildImplIndex(outgoing);
+    const mainRefs = outgoing.filter((r) => !r.implementationOf);
+    lines.push("");
+    lines.push("#### Outgoing Calls:");
+    const groups = groupByDeclaringType(mainRefs);
+    for (const g of groups) {
+      lines.push(formatRefGroup(g, implIndex, viewScope));
+    }
+  }
+
+  if (incoming.length > 0) {
+    const implIndex = buildImplIndex(incoming);
+    const mainRefs = incoming.filter((r) => !r.implementationOf);
+    lines.push("");
+    lines.push("#### Incoming Calls:");
+    const groups = groupByDeclaringType(mainRefs);
+    for (const g of groups) {
+      lines.push(formatRefGroup(g, implIndex, viewScope));
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export const help = `Print source code of a type or method with resolved references.
+
+Returns markdown with source in a code block and references split into:
+- Outgoing Calls — what this method/type calls or references
+- Incoming Calls — who calls this method/type (when available)
+
+References are grouped by declaring type. Each has a badge
+([M] method, [C] class, [I] interface, [E] enum, [K] constant,
+[F] field, [A] annotation) and metadata (static, inherited,
+return type with kind).
+
+Usage:  jdt source <FQMN> [<FQMN> ...] [--json]
 
-Usage:  jdt source <FQN>[#method[(param types)]]
+Flags:
+  --json    output raw JSON from the server (for debugging)
 
 Examples:
-  jdt source app.m8.dao.StaffDaoImpl
-  jdt source app.m8.dao.StaffDaoImpl#getStaff
-  jdt source "app.m8.dao.StaffDaoImpl#save(Order)"`;
+  jdt source com.example.dao.UserDaoImpl
+  jdt source com.example.dao.UserDaoImpl#getStaff
+  jdt source "com.example.dao.UserDaoImpl#save(Order)"
+  jdt source com.example.Foo#bar --json`;

package/src/commands/subtypes.mjs

@@ -30,4 +30,4 @@ export const help = `Find all direct and indirect subtypes/implementors of a typ
 
 Usage:  jdt subtypes <FQN>
 
-Example:  jdt subtypes app.m8.web.shared.core.HasId`;
+Example:  jdt subtypes com.example.core.HasId`;

package/src/commands/test-run.mjs

@@ -0,0 +1,100 @@
+import { get } from "../client.mjs";
+import { extractPositional, parseFlags, parseFqmn } from "../args.mjs";
+import {
+  formatTestRunHeader,
+  testRunGuide,
+  followTestStream,
+} from "../format/test-status.mjs";
+
+/**
+ * Launch tests non-blocking. Analogous to `jdt launch run`.
+ * Without -f: prints header + onboarding guide.
+ * With -f: prints header + streams test progress until done.
+ */
+export async function testRun(args) {
+  // Filter out single-char flags (-f, -q) before extracting positionals
+  const filtered = args.filter((a) => a !== "-f" && a !== "-q");
+  const pos = extractPositional(filtered);
+  const flags = parseFlags(args);
+
+  let url = "/test/run?";
+  const parsed = parseFqmn(pos[0]);
+  const fqn = parsed.className;
+
+  if (fqn) {
+    url += `class=${encodeURIComponent(fqn)}`;
+    const method = parsed.method;
+    if (method) url += `&method=${encodeURIComponent(method)}`;
+  } else if (flags.project) {
+    url += `project=${encodeURIComponent(flags.project)}`;
+    if (flags.package)
+      url += `&package=${encodeURIComponent(flags.package)}`;
+  } else {
+    console.error(
+      "Usage: test run <FQN>[#method] | test run --project <name> [--package <pkg>]",
+    );
+    process.exit(1);
+  }
+
+  if (args.includes("--no-refresh")) url += "&no-refresh";
+
+  const result = await get(url, 30_000);
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+
+  // Wait briefly for session to register total count
+  const session = result.session;
+  await sleep(500);
+  try {
+    const status = await get(
+      `/test/status?session=${encodeURIComponent(session)}`,
+      5_000,
+    );
+    if (status && !status.error && status.total > 0) {
+      result.total = status.total;
+      if (status.label) result.label = status.label;
+    }
+  } catch {
+    // ignore — total just won't be shown
+  }
+
+  console.log(formatTestRunHeader(result));
+
+  const follow = args.includes("-f") || args.includes("--follow");
+  if (follow) {
+    console.log();
+    const exitCode = await followTestStream(session, args);
+    process.exit(exitCode);
+  }
+
+  const quiet = args.includes("-q") || args.includes("--quiet");
+  if (!quiet) {
+    console.log(testRunGuide(session));
+  }
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+export const help = `Launch tests non-blocking with real-time progress.
+
+Usage:  jdt test run <FQN>[#method] [-f] [-q]
+        jdt test run --project <name> [--package <pkg>] [-f] [-q]
+
+Without -f, launches and prints a guide with available commands.
+With -f, launches and streams test progress until completion.
+
+Flags:
+  -f, --follow    stream test status (only failures by default)
+  -q, --quiet     suppress onboarding guide
+  --all           include passed tests in output (with -f)
+  --ignored       show only ignored tests (with -f)
+
+Examples:
+  jdt test run com.example.MyTest                 run + show guide
+  jdt test run com.example.MyTest -f              run + stream failures
+  jdt test run com.example.MyTest -f --all        run + stream all tests
+  jdt test run --project my-project -f             run project tests + stream`;

package/src/commands/test-sessions.mjs

@@ -0,0 +1,46 @@
+import { get } from "../client.mjs";
+import { green, red, yellow, dim } from "../color.mjs";
+
+/**
+ * List active and completed test sessions.
+ */
+export async function testSessions() {
+  const results = await get("/test/sessions");
+  if (results.error) {
+    console.error(results.error);
+    process.exit(1);
+  }
+  if (results.length === 0) {
+    console.log("(no test sessions)");
+    return;
+  }
+  for (const s of results) {
+    const label = s.label || s.session;
+    const counts = formatCounts(s);
+    const time =
+      Number.isFinite(s.time) && s.time > 0
+        ? `${s.time.toFixed(1)}s`
+        : "";
+    const state = s.state === "running"
+      ? `running (${s.completed}/${s.total})`
+      : s.state;
+    console.log(
+      `${s.session}  ${label}  ${s.total} tests  ${counts}  ${time}  ${state}`,
+    );
+  }
+}
+
+function formatCounts(s) {
+  const parts = [];
+  if (s.passed > 0) parts.push(green(`${s.passed} passed`));
+  if (s.failed > 0) parts.push(red(`${s.failed} failed`));
+  if (s.errors > 0) parts.push(red(`${s.errors} errors`));
+  if (s.ignored > 0) parts.push(yellow(`${s.ignored} ign`));
+  return parts.join(", ");
+}
+
+export const help = `List active and completed test sessions.
+
+Usage:  jdt test sessions
+
+Output: session ID, label, test counts, state — one session per line.`;

package/src/commands/test-status.mjs

@@ -0,0 +1,59 @@
+import { get } from "../client.mjs";
+import { extractPositional } from "../args.mjs";
+import {
+  formatTestStatus,
+  followTestStream,
+} from "../format/test-status.mjs";
+
+/**
+ * Show test session status (snapshot or stream).
+ * Analogous to `jdt launch logs`.
+ */
+export async function testStatus(args) {
+  const pos = extractPositional(args);
+  const session = pos[0];
+
+  if (!session) {
+    console.error("Usage: test status <session> [-f] [--all] [--ignored]");
+    process.exit(1);
+  }
+
+  const follow = args.includes("-f") || args.includes("--follow");
+  if (follow) {
+    const exitCode = await followTestStream(session, args);
+    process.exit(exitCode);
+  }
+
+  // Snapshot mode
+  let filter = "failures";
+  if (args.includes("--all")) filter = "all";
+  else if (args.includes("--ignored")) filter = "ignored";
+
+  let url = `/test/status?session=${encodeURIComponent(session)}`;
+  if (filter) url += `&filter=${filter}`;
+
+  const result = await get(url, 30_000);
+  if (result.error) {
+    console.error(result.error);
+    process.exit(1);
+  }
+
+  formatTestStatus(result);
+}
+
+export const help = `Show test session status (snapshot or live stream).
+
+Usage:  jdt test status <session> [-f] [--all] [--ignored]
+
+Without -f, returns a snapshot of the current state.
+With -f, streams test events until the session completes.
+
+Flags:
+  -f, --follow    stream events live until completion
+  --all           show all tests (default: failures only)
+  --ignored       show only ignored/skipped tests
+
+Examples:
+  jdt test status jdtbridge-test-1234567890
+  jdt test status jdtbridge-test-1234567890 -f
+  jdt test status jdtbridge-test-1234567890 --ignored`;

package/src/commands/type-info.mjs

@@ -44,4 +44,4 @@ export const help = `Show class overview: fields, methods, modifiers, and line n
 
 Usage:  jdt type-info <FQN>
 
-Example:  jdt type-info app.m8.dto.web.core.IdOrgRoot`;
+Example:  jdt type-info com.example.dto.BaseEntity`;

package/src/format/hierarchy.mjs

@@ -0,0 +1,47 @@
+const TYPE_KIND_BADGE = {
+  class: "[C]",
+  interface: "[I]",
+  enum: "[E]",
+  annotation: "[A]",
+};
+
+export function formatHierEntry(arrow, s) {
+  const depth = s.depth || 0;
+  const indent = "  ".repeat(depth);
+  const b = TYPE_KIND_BADGE[s.kind] || "[C]";
+  const prefix = arrow ? `${arrow} ` : "";
+  let line = `${indent}- ${prefix}${b} \`${s.fqn}\``;
+  if (s.anonymous && s.enclosingFqmn) {
+    line += ` — in \`${s.enclosingFqmn}\``;
+  }
+  const lines = [line];
+  if (s.file) {
+    let loc = s.file;
+    if (s.line) {
+      loc += `:${s.line}`;
+      if (s.endLine && s.endLine !== s.line) loc += `-${s.endLine}`;
+    }
+    lines.push(`${indent}  \`${loc}\``);
+  }
+  return lines;
+}
+
+export function formatHierarchy(result) {
+  const lines = [];
+  const supers = result.supertypes || [];
+  const subs = result.subtypes || [];
+  if (supers.length > 0) {
+    lines.push("#### Supertypes:");
+    for (const s of supers) {
+      lines.push(...formatHierEntry("↑", s));
+    }
+  }
+  if (subs.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push("#### Subtypes:");
+    for (const s of subs) {
+      lines.push(...formatHierEntry("", s));
+    }
+  }
+  return lines;
+}

package/src/format/test-results.mjs

@@ -20,7 +20,7 @@ export function formatTestResults(result) {
     for (const f of result.failures) {
       const status =
         f.status === "FAILURE" ? red(f.status) : bold(red(f.status));
-      console.log(`${status}  ${f.class}.${f.method}`);
+      console.log(`${status} [M] \`${f.class}#${f.method}\``);
       if (f.trace) {
         const traceLines = f.trace.split("\n").slice(0, 10);
         for (const line of traceLines) console.log(`  ${line}`);

package/src/format/test-status.mjs

@@ -0,0 +1,221 @@
+// Test status formatter.
+// Formats test session snapshots and streaming JSONL events.
+// Uses FQMN with # separator and [M] badges for navigation.
+
+import { red, green, yellow, bold, dim } from "../color.mjs";
+
+/**
+ * Format a test status snapshot (JSON from /test/status).
+ * Shows summary line + failure/ignored details based on filter.
+ */
+export function formatTestStatus(result) {
+  const state = result.state === "running"
+    ? " (running)"
+    : result.state === "stopped"
+      ? " (stopped)"
+      : "";
+
+  const label = result.label || result.session;
+  const progress = result.state === "running"
+    ? `${result.completed}/${result.total}`
+    : `${result.total}/${result.total}`;
+
+  console.log(
+    `#### ${label} — ${progress}${state}, ${formatCounts(result)}`,
+  );
+
+  const entries = result.entries || result.failures || [];
+  if (entries.length > 0) {
+    console.log();
+    for (const f of entries) {
+      formatEntry(f);
+    }
+  }
+}
+
+/**
+ * Format a single JSONL event line from the stream.
+ * Returns true if something was printed.
+ */
+export function formatTestEvent(jsonLine) {
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonLine);
+  } catch {
+    return false;
+  }
+
+  if (parsed.event === "started") {
+    // Header already printed by test-run, skip in stream
+    return false;
+  }
+
+  if (parsed.event === "finished") {
+    console.log();
+    console.log(formatCounts(parsed));
+    return true;
+  }
+
+  if (parsed.event === "case") {
+    const status = parsed.status;
+    const fqmn = parsed.fqmn;
+    const time = formatTime(parsed.time);
+
+    if (status === "PASS") {
+      console.log(`${green("PASS")} [M] \`${fqmn}\` ${dim(time)}`);
+    } else if (status === "FAIL") {
+      console.log(`${red("FAIL")} [M] \`${fqmn}\` ${dim(time)}`);
+      printTrace(parsed);
+    } else if (status === "ERROR") {
+      console.log(
+        `${bold(red("ERROR"))} [M] \`${fqmn}\` ${dim(time)}`,
+      );
+      printTrace(parsed);
+    } else if (status === "IGNORED") {
+      console.log(
+        `${yellow("IGNORED")} [M] \`${fqmn}\``,
+      );
+    }
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Format a single entry from status snapshot (PASS, FAIL, ERROR, IGNORED).
+ */
+function formatEntry(f) {
+  const status = f.status;
+  const fqmn = f.fqmn;
+  const time = formatTime(f.time);
+
+  if (status === "PASS") {
+    console.log(`${green("PASS")} [M] \`${fqmn}\` ${dim(time)}`);
+  } else if (status === "FAIL") {
+    console.log(`${red("FAIL")} [M] \`${fqmn}\` ${dim(time)}`);
+    printTrace(f);
+  } else if (status === "ERROR") {
+    console.log(
+      `${bold(red("ERROR"))} [M] \`${fqmn}\` ${dim(time)}`,
+    );
+    printTrace(f);
+  } else if (status === "IGNORED") {
+    console.log(`${yellow("IGNORED")} [M] \`${fqmn}\``);
+  }
+}
+
+function printTrace(parsed) {
+  if (parsed.expected != null && parsed.actual != null) {
+    console.log(`  Expected: ${parsed.expected}`);
+    console.log(`  Actual: ${parsed.actual}`);
+  }
+  if (parsed.trace) {
+    const lines = parsed.trace.split("\n").slice(0, 10);
+    for (const line of lines) console.log(`  ${line}`);
+    if (parsed.trace.split("\n").length > 10) console.log("  ...");
+  }
+}
+
+function formatCounts(r) {
+  const parts = [`${r.total} tests`];
+  if (r.passed > 0) parts.push(green(`${r.passed} passed`));
+  if (r.failed > 0) parts.push(red(`${r.failed} failed`));
+  if (r.errors > 0) parts.push(red(`${r.errors} errors`));
+  if (r.ignored > 0) parts.push(yellow(`${r.ignored} ignored`));
+  const time = Number.isFinite(r.time) ? r.time : 0;
+  parts.push(`${time.toFixed(1)}s`);
+  return parts.join(", ");
+}
+
+function formatTime(t) {
+  if (t == null || !Number.isFinite(t)) return "";
+  return `(${t.toFixed(3)}s)`;
+}
+
+/**
+ * Format the header printed at test run start.
+ * Markdown-friendly: heading + backtick-wrapped values.
+ */
+export function formatTestRunHeader(result) {
+  const label = result.label || result.session;
+  const total = result.total ? ` (${result.total} tests)` : "";
+  const parts = [`#### Test: ${label}${total}`];
+  parts.push(`Launch: \`${result.session}\``);
+  if (result.project) parts.push(`Project: \`${result.project}\``);
+  if (result.runner) parts.push(`Runner: ${result.runner}`);
+  return parts.join("\n");
+}
+
+/**
+ * Onboarding guide printed after non-blocking launch.
+ * Markdown-friendly: bold sections, backtick commands.
+ */
+export function testRunGuide(session) {
+  return `
+**Status** — snapshot or live stream:
+  \`jdt test status ${session}\`        failures only (default)
+  \`jdt test status ${session} -f\`     stream live until done
+  \`jdt test status ${session} --all\`  all tests including passed
+  \`jdt test status ${session} --ignored\`  only skipped/disabled tests
+
+**Console** — raw stdout/stderr of the test JVM:
+  \`jdt launch logs ${session}\`
+
+**Manage:**
+  \`jdt test sessions\`                 list active/completed sessions
+  \`jdt launch stop ${session}\`   abort
+  \`jdt launch clear ${session}\`  remove
+
+**Navigate** — FQMNs from status output are copy-pasteable:
+  \`jdt source <FQMN>\`                 view test source
+  \`jdt test run <FQMN> -f\`            re-run single test
+
+Add \`-q\` to suppress this guide.`;
+}
+
+/**
+ * Stream test status via JSONL and format output.
+ * Shared by test-run -f and test-status -f.
+ * Returns exit code: 0 if all pass, 1 if any failures.
+ */
+export async function followTestStream(session, args) {
+  const { getStreamLines } = await import("../client.mjs");
+
+  let filter = "failures";
+  if (args.includes("--all")) filter = "all";
+  else if (args.includes("--ignored")) filter = "ignored";
+
+  const url = `/test/status/stream?session=${encodeURIComponent(session)}&filter=${filter}`;
+
+  let detached = false;
+  const onSigint = () => {
+    detached = true;
+    process.stdout.write("\n");
+    process.exit(0);
+  };
+  process.on("SIGINT", onSigint);
+
+  let hasFailed = false;
+  try {
+    await getStreamLines(url, (line) => {
+      formatTestEvent(line);
+      try {
+        const ev = JSON.parse(line);
+        if (ev.event === "finished"
+            && (ev.failed > 0 || ev.errors > 0)) {
+          hasFailed = true;
+        }
+      } catch { /* ignore parse errors */ }
+    });
+  } catch (e) {
+    if (!detached) {
+      console.error(e.message);
+      return 1;
+    }
+    return 0;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+  return hasFailed ? 1 : 0;
+}

package/src/commands/test.mjs

@@ -1,48 +0,0 @@
-import { get } from "../client.mjs";
-import { extractPositional, parseFlags, parseFqmn } from "../args.mjs";
-import { formatTestResults } from "../format/test-results.mjs";
-
-export async function test(args) {
-  const pos = extractPositional(args);
-  const flags = parseFlags(args);
-  let url = "/test?";
-  const parsed = parseFqmn(pos[0]);
-  const fqn = parsed.className;
-  if (fqn) {
-    url += `class=${encodeURIComponent(fqn)}`;
-    const method = parsed.method || pos[1];
-    if (method) url += `&method=${encodeURIComponent(method)}`;
-  } else if (flags.project) {
-    url += `project=${encodeURIComponent(flags.project)}`;
-    if (flags.package)
-      url += `&package=${encodeURIComponent(flags.package)}`;
-  } else {
-    console.error(
-      "Usage: test <FQN> [method] | test --project <name> [--package <pkg>]",
-    );
-    process.exit(1);
-  }
-  if (flags.timeout) url += `&timeout=${flags.timeout}`;
-  if (args.includes("--no-refresh")) url += "&no-refresh";
-  const result = await get(url, 300_000);
-  if (result.error) {
-    console.error(result.error);
-    process.exit(1);
-  }
-  formatTestResults(result);
-}
-
-export const help = `Run JUnit tests via Eclipse's built-in test runner.
-
-Usage:  jdt test <FQN>[#method]
-        jdt test --project <name> [--package <pkg>]
-
-Flags:
-  --project <name>   run all tests in a project
-  --package <pkg>    narrow to a specific package (with --project)
-  --timeout <sec>    test run timeout in seconds (default: 120)
-
-Examples:
-  jdt test app.m8ws.utils.ObjectMapperTest
-  jdt test app.m8ws.utils.ObjectMapperTest#testSerialize
-  jdt test --project m8-server`;