@appthreat/chennai 0.0.1 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) AppThreat
+Copyright (c) 2025 AppThreat
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,293 @@
-# @appthreat/chennai
+# chennai
 
-Interactive terminal UI for exploring AppThreat atom files with AI agent.
+chennai (chen & ai) is a hybrid AI agent and a terminal user interface for exploring AppThreat [atom](https://github.com/AppThreat/atom) files. It is built on top of the [chen](https://github.com/AppThreat/chen) library (Code Hierarchy Exploratory Network) and provides a keyboard-driven interactive environment for static analysis, data-flow tracing, and AI-assisted code and security analysis.
 
-This is a placeholder package used to enable npm trusted publishing.
+Unlike a traditional SAST engine or a generic LLM chatbot, chennai gives you direct access to the underlying graph queries so you can ask arbitrary questions about a program's structure and data flows without leaving the terminal. It runs entirely on your machine with no server backend and no data leaving your environment.
+
+chennai includes a built-in AI agent that uses atom as grounding context. The agent can run chen DSL queries, traverse data-flow paths, run graph algorithms, read source files, and search code with ripgrep, all orchestrated from a single chat interface inside the TUI. The agent supports both Anthropic and OpenAI compatible providers and can work either with or without an LLM.
+
+## Use cases
+
+- Interactive exploration of atom files generated by the atom tool. Open an atom, browse methods, calls, namespaces, tags, and literals without writing queries by hand.
+- Data-flow analysis with source to sink tracing. The TUI displays flows with grouped paths, sub-flow toggling, and mitigation indicators.
+- Graph algorithm execution including PageRank, strongly connected components, topological sort, dominator trees, and interprocedural path finding.
+- AI-assisted vulnerability analysis with slash commands for security review, code review, explain, and trace. The agent routes tool calls through the engine and returns structured findings.
+- REPL-driven querying with tab completions, command history, and the full chen DSL available through the eval command.
+
+## Requirements
+
+- An atom file (from the atom tool) to open. The atom file is a Code Property Graph produced by running atom against a codebase.
+- Java 23 or newer if running the engine via the JAR fallback distribution.
+- At least 4GB of available memory for the TUI and engine together. Larger codebases may need more.
+
+## Installation
+
+chennai is distributed as an npm package with platform-specific native binaries.
+
+```
+npm install -g @appthreat/chennai
+```
+
+After installation the `chennai` command is available globally.
+
+```
+chennai <path-to-atom-file-or-directory> [options]
+```
+
+## Setup
+
+The `chennai setup` command installs or updates the required analysis tools (cdxgen, atom, atom-parsetools) via npm:
+
+```
+chennai setup
+```
+
+This runs `npm install -g --ignore-scripts @cyclonedx/cdxgen @appthreat/atom @appthreat/atom-parsetools`.
+
+### Tool discovery
+
+chennai auto-detects these tools in the following order:
+
+| Tool   | Env var      | Search path                                    |
+| ------ | ------------ | ---------------------------------------------- |
+| cdxgen | `CDXGEN_CMD` | PATH → `node_modules/.bin/cdxgen` → npm global |
+| atom   | `ATOM_CMD`   | `ATOM_CMD` → PATH                              |
+| npm    | —            | PATH                                           |
+
+### Atom auto-generation
+
+When you point chennai at a project directory that has no `.atom` file, it will prompt you to generate one interactively:
+
+```
+$ chennai /path/to/project
+No .atom file found in /path/to/project
+Generate one for analysis?  This will:
+  └ 1. Run cdxgen to produce a CycloneDX SBOM
+  └ 2. Run atom --with-data-deps to build the atom file
+
+Source: /path/to/project [Y/n]
+```
+
+If the tools are not installed but `npm` is available, chennai offers to install them automatically before proceeding.
+
+### Software Bill of Materials
+
+chennai integrates with [cdxgen](https://github.com/AppThreat/cdxgen) to automatically generate and load CycloneDX SBOMs for deeper dependency-aware analysis. When you invoke chennai with a source or reports directory, it first looks for any existing `.cdx.json` files. If none are found, it invokes cdxgen to create a BOM with the naming convention `sbom-<language>-<lifecycle>.cdx.json`.
+
+#### Installing cdxgen (recommended for best experience)
+
+```
+npm install -g @cyclonedx/cdxgen
+```
+
+cdxgen will be auto-detected in PATH. You can also set the `CDXGEN_CMD` environment variable to point to a custom location. Once installed, chennai will automatically generate BOMs on startup when a source directory is available.
+
+### BOM commands
+
+| Command       | Description                                                    |
+| ------------- | -------------------------------------------------------------- |
+| `bom`         | Display all BOM components as a searchable, sortable table     |
+| `bom <query>` | Filter BOM components by name, type, version, PURL, or license |
+
+The BOM data is also injected into AI agent prompts for security and code reviews, improving the LLM's understanding of third-party dependencies, their licenses, and known vulnerabilities.
+
+### Options
+
+| Option               | Default               | Description                                         |
+| -------------------- | --------------------- | --------------------------------------------------- |
+| `--engine PATH`      | auto                  | Path to the chennai-engine binary                   |
+| `--theme dark/light` | dark                  | Color theme                                         |
+| `--source PATH`      | atom dir              | Project source root for file resolution             |
+| `--ask TEXT`         | --                    | Headless mode: ask a question and print the answer  |
+| `--provider STR`     | anthropic             | LLM provider (anthropic or openai)                  |
+| `--model STR`        | claude-opus-4-8       | LLM model name                                      |
+| `--api-key STR`      | env var               | API key for the LLM provider                        |
+| `--base-url STR`     | --                    | Custom API base URL for OpenAI-compatible endpoints |
+| `--reports-dir PATH` | .chen/chennai-reports | Directory for markdown reports and BOM files        |
+| `--no-thinking`      | false                 | Omit thinking blocks from the LLM request           |
+| `--effort STR`       | high                  | Reasoning effort (low, medium, high, xhigh, max)    |
+
+### Environment variables
+
+- `CHENNAI_ENGINE`: Path to the engine binary. Overrides auto-detection.
+- `ANTHROPIC_API_KEY`: API key for Anthropic provider.
+- `OPENAI_API_KEY`: API key for OpenAI-compatible providers.
+- `CDXGEN_CMD`: Path to the cdxgen binary.
+- `ATOM_CMD`: Path to the atom CLI binary (e.g. `/path/to/atom/atom.sh`).
+- `CHENNAI_DEBUG`: Set to any value to enable resolver diagnostics.
+
+### Platform support
+
+| Platform | Architecture      | Engine        | TUI           |
+| -------- | ----------------- | ------------- | ------------- |
+| Linux    | x64 (glibc)       | native        | native        |
+| Linux    | arm64 (glibc)     | native        | native        |
+| Linux    | x64 (musl/Alpine) | native (musl) | native (musl) |
+| macOS    | Apple Silicon     | native        | native        |
+| Windows  | x64               | native        | native        |
+
+Other platforms fall back to the JAR distribution for the engine while the TUI runs natively where available.
+
+## Architecture
+
+chennai has two processes that communicate over NDJSON on stdin/stdout.
+
+### Engine (chennai-engine)
+
+The engine is a Scala 3 application built with the chen library. It reads atom files and runs queries against the atom file. It is distributed as a GraalVM native-image binary on supported platforms and as a JAR distribution elsewhere.
+
+The engine accepts NDJSON request lines on stdin and writes NDJSON response lines to stdout. Each request has an id, a command, and arguments. The engine opens an atom file on startup and keeps it in memory for the duration of the session.
+
+### TUI (chennai)
+
+The TUI is a Rust application using ratatui and crossterm. It spawns the engine as a child process, opens the atom file, and presents a three-panel interface: a summary panel with row counts, a REPL panel for input, and an output panel for results. The TUI auto-detects the engine binary location -- by default it looks for chennai-engine in the same directory, then checks the standard development build paths.
+
+## User interface
+
+The TUI has three panels navigated with Tab and Shift+Tab.
+
+### Summary panel
+
+Displays the atom summary: language, version, and row counts for files, methods, calls, literals, namespaces, annotations, config files, and dependencies. Pressing Enter on a row runs a query for that type and displays results in the output panel.
+
+### REPL panel
+
+A command-line input at the bottom of the screen. Enter queries here to run them. The REPL supports:
+
+- Command labels: `files`, `methods`, `calls`, `external methods`, `internal methods`, `namespaces`, `annotations`, `imports`, `literals`, `config files`
+- DSL expressions: any chen DSL expression such as `atom.method.name(".*Handler")`
+- Tag queries: `atom.tag.name("crypto.*")`
+- Flow presets: `dataflows`, `reachables`, `cryptos`
+- Custom flow DSL: expressions containing `reachableByFlows` or `.df(`
+- DSL prefix with `=`: forces raw eval mode, e.g. `=atom.call.code(".*query.*")`
+
+Tab completions are available with Ctrl+Space. Command history is accessible with Up and Down arrows.
+
+### Output panel
+
+Displays query results. The output panel has several display modes:
+
+**Table view**: Query results are shown as a scrollable, sortable table. Columns are sorted by pressing 1 through 9. Filter rows with /. Press Enter to open a detail pane for a row. The detail pane shows node properties, a child table (arguments, parameters, locals), and source code side by side.
+
+**Flow view**: Data-flow paths are displayed as master-detail groups. Each group represents a source to sink path. Groups can be collapsed. Sub-flows are shown with `s` and mitigated flows (passing through sanitizers or validators) can be hidden with `m`.
+
+**Agent view**: The AI agent output is rendered as a streaming transcript with thinking blocks, tool calls, and results. Tools results that return flow data can be installed into the flow view for further exploration.
+
+### Keybindings
+
+| Key                          | Action                              |
+| ---------------------------- | ----------------------------------- |
+| q                            | Quit                                |
+| Tab / Shift+Tab              | Cycle panels forward/backward       |
+| Up/Down (or j/k)             | Navigate lists, scroll output       |
+| PageUp/PageDown (or b/Space) | Page through lists                  |
+| Enter                        | Open detail or execute command      |
+| /                            | Filter table in output panel        |
+| 1-9                          | Sort table by column                |
+| s                            | Toggle sub-flows in flow view       |
+| m                            | Toggle mitigated flows in flow view |
+| d / r                        | Run dataflows or reachables preset  |
+| Ctrl+S                       | Save report to markdown file        |
+
+## DSL queries and traversals
+
+The full chen DSL is available through the eval command. The reference documentation for all traversal steps and node types is maintained in the chen repository at `docs/TRAVERSAL.md`. The atom repository at `docs/lessons/` has nineteen lessons covering everything from frontend setup through data-flow analysis and graph algorithms.
+
+The entry point for queries is `atom`, representing the root of the Code Property Graph. Common starters include `atom.file`, `atom.method`, `atom.call`, `atom.literal`, `atom.tag`, and `atom.namespace`. These can be chained with steps like `.name(".*Handler")`, `.isExternal(false)`, `.callee`, `.caller`, `.cfgNext`, `.dominatedBy`, and many others.
+
+For type-based filtering the DSL provides `.isCall`, `.isLiteral`, `.isIdentifier`, `.isMethod`, `.isFile`, and similar predicates on any AST node.
+
+## Data-flow analysis
+
+chennai supports three flow presets accessible from the REPL or the summary panel:
+
+- `dataflows`: Runs reachableByFlows from framework-input tagged sources to framework-output tagged sinks.
+- `reachables`: Runs reachableByFlows using the default reachables configuration.
+- `cryptos`: Runs crypto-related data-flow analysis.
+
+Custom flow queries use the `reachableByFlows` or `df` steps. For example:
+
+```
+atom.call.name(".*execute.*").reachableByFlows(atom.call.name(".*getInput.*"))
+```
+
+The flow view groups results by source-sink pair, shows each step in the path, and indicates methods that have sanitization or validation tags. The engine supports two reaching-definitions solvers: the default Flux solver (low-allocation, fast on large methods) and a classic solver for comparison.
+
+## Graph algorithms
+
+Run via the `algo` command in the engine. Available algorithms:
+
+- **PageRank** (`centrality`): Ranks methods by PageRank score and in-degree centrality on the call graph.
+- **Strongly connected components** (`scc`): Finds recursion clusters in the call graph.
+- **Topological sort** (`toposort`): Orders methods callee-before-caller, grouped by SCC.
+- **Dominator tree** (`dominators`): Computes immediate dominators per method over CFG edges.
+- **Interprocedural paths** (`paths`): Finds BFS-limited call paths between a source and target method.
+
+## AI agent
+
+When an API key is configured (via environment variable or config file), the slash commands activate. These are entered in the REPL panel like any other command.
+
+### Slash commands
+
+| Command            | Purpose                                                                                                                                             |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/security-review` | Reachability-grounded vulnerability analysis. Finds source-to-sink taint paths, ranks findings, and produces a markdown report. Uses `high` effort. |
+| `/code-review`     | Review code changes (diff or methods) for correctness and security. Uses `medium` effort.                                                           |
+| `/explain`         | Natural-language explanation of a method, data-flow, or code structure. Uses `medium` effort.                                                       |
+| `/trace`           | Prove or disprove a taint path between a given source and sink. Uses `high` effort.                                                                 |
+| `/help`            | List available slash commands.                                                                                                                      |
+
+Free text input (without a slash) is also routed to the agent for ad hoc questions. The agent has access to thirteen tools: atom_summary, atom_query, atom_dsl_eval, atom_flows, atom_flows_through, atom_detail, atom_algorithms, bom_query, ripgrep, read_file, git_diff, git_log, and git_show.
+
+The agent uses the streaming API of the configured provider and renders thinking blocks, text deltas, and tool calls in real time. Tool results are truncated to 48 KiB to stay within model token limits. When the agent produces flow results they are automatically installed into the flow view for interactive exploration.
+
+Agent reports can be saved to markdown with Ctrl+S. Reports include the full transcript, token usage, and any generated data-flow paths or analysis results.
+
+### Offline operation
+
+The agent is optional. When no API key is set, chennai operates as a fully offline code analysis tool with all query, data-flow, and algorithm features available through the REPL. The slash commands and free-text agent features only activate when a provider is configured.
+
+## Configuration
+
+The agent can be configured with a TOML file at `~/.config/chennai/config.toml`, environment variables, or CLI flags. CLI flags take precedence over environment variables, which take precedence over the config file.
+
+Example config file:
+
+```toml
+provider = "openai"
+model = "deepseek-chat"
+api_key = "sk-..."
+base_url = "https://api.deepseek.com"
+effort = "high"
+```
+
+## Developing
+
+### Prerequisites
+
+- Rust toolchain (edition 2024)
+- Scala 3.8.4 and sbt
+- GraalVM Community Edition 25 for native-image builds (optional for development)
+
+### Build
+
+```
+# Engine (staged JAR distribution)
+(cd engine && sbt stage)
+
+# Engine native image (requires GraalVM)
+bash ci/native-image.sh
+
+# TUI
+(cd tui && cargo build --release)
+```
+
+### Build all npm packages locally
+
+```
+bash wrapper/nodejs/scripts/build-local.sh
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import { platform as _platform } from "node:os";
+import { dirname, join } from "node:path";
+import { readFileSync, realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { locateChennaiBinary, describeChennaiSearch } from "./resolve.js";
+
+const isWin = _platform() === "win32";
+const dirName = dirname(fileURLToPath(import.meta.url));
+const selfPJson = JSON.parse(readFileSync(join(dirName, "package.json"), "utf8"));
+
+export const CHENNAI_VERSION = selfPJson.version;
+
+const provider = locateChennaiBinary();
+
+export const executeChennai = (chennaiArgs) => {
+  if (!provider) {
+    console.error("Error: The '@appthreat/chennai' package was not installed correctly or is unsupported on this platform.");
+    console.error("Please verify your installation and make sure optional dependencies are not blocked.");
+    try {
+      const diag = describeChennaiSearch();
+      console.error(
+        `\n[chennai] resolution diagnostics:\n` +
+        `  dispatcher dir: ${diag.selfDir}\n` +
+        `  platform=${diag.platform} arch=${diag.arch} libc=${diag.libc}\n` +
+        `  preferred package: ${diag.preferredPkg}\n` +
+        `  paths checked (${diag.attempts.length}):`
+      );
+      for (const a of diag.attempts) {
+        console.error(`    [${a.exists ? "found" : "missing"}] (${a.pkg}, ${a.kind}) ${a.path}`);
+      }
+    } catch (e) {
+      console.error(`[chennai] failed to produce diagnostics: ${e?.message || e}`);
+    }
+    process.exit(1);
+  }
+
+  const cwd = process.env.CHENNAI_CWD || process.cwd();
+  const timeout = process.env.CHENNAI_TIMEOUT ? parseInt(process.env.CHENNAI_TIMEOUT, 10) : undefined;
+
+  const env = { ...process.env };
+  if (provider.enginePath) {
+    env.CHENNAI_ENGINE = provider.enginePath;
+  }
+
+  const result = spawnSync(provider.binPath, chennaiArgs, {
+    encoding: "utf-8",
+    env,
+    cwd,
+    stdio: "inherit",
+    timeout,
+  });
+  process.exit(result.status !== null ? result.status : 1);
+};
+
+if (process.argv[1]) {
+  const argv = process.argv.slice(2);
+  executeChennai(argv);
+}

package/package.json

@@ -1,15 +1,46 @@
 {
   "name": "@appthreat/chennai",
-  "version": "0.0.1",
-  "description": "[placeholder] Interactive terminal UI for exploring AppThreat atom files with AI agent",
+  "version": "0.3.0",
+  "description": "Interactive terminal UI for exploring AppThreat atom files with AI agent",
+  "exports": "./index.js",
+  "type": "module",
+  "bin": {
+    "chennai": "index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AppThreat/chennai.git"
   },
+  "keywords": [
+    "code",
+    "analysis",
+    "threat",
+    "tui",
+    "cpg"
+  ],
   "author": "Team AppThreat <cloud@appthreat.com>",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/AppThreat/chennai/issues"
   },
-  "homepage": "https://github.com/AppThreat/chennai#readme"
+  "homepage": "https://github.com/AppThreat/chennai#readme",
+  "files": [
+    "index.js",
+    "resolve.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "optionalDependencies": {
+    "@appthreat/chennai-linux-amd64": "0.3.0",
+    "@appthreat/chennai-linux-arm64": "0.3.0",
+    "@appthreat/chennai-darwin-arm64": "0.3.0",
+    "@appthreat/chennai-darwin-amd64": "0.3.0",
+    "@appthreat/chennai-windows-amd64": "0.3.0",
+    "@appthreat/chennai-windows-arm64": "0.3.0",
+    "@appthreat/chennai-linux-amd64-musl": "0.3.0",
+    "@appthreat/chennai-linux-arm64-musl": "0.3.0"
+  }
 }

package/resolve.js

@@ -0,0 +1,226 @@
+import { dirname, join, sep } from "node:path";
+import fs from "node:fs";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const SELF_DIR = dirname(fileURLToPath(import.meta.url));
+
+const NATIVE_PACKAGES = new Set([
+  "@appthreat/chennai-linux-amd64",
+  "@appthreat/chennai-linux-arm64",
+  "@appthreat/chennai-darwin-arm64",
+  "@appthreat/chennai-windows-amd64",
+  "@appthreat/chennai-linux-amd64-musl",
+]);
+
+export function getLinuxLibc() {
+  if (process.platform !== "linux") return null;
+  try {
+    const report = process.report?.getReport();
+    if (typeof report === "object" && report?.header) {
+      if (report.header.glibcVersionRuntime) return "glibc";
+    }
+  } catch (_) {}
+  try {
+    if (fs.existsSync("/etc/alpine-release")) return "musl";
+  } catch (_) {}
+  try {
+    const out = execSync("ldd --version", { stdio: ["ignore", "pipe", "ignore"] }).toString();
+    if (out.includes("musl")) return "musl";
+  } catch (_) {}
+  return "glibc";
+}
+
+export function resolveChennaiProvider(opts = {}) {
+  const platform = opts.platform || process.platform;
+  const arch = opts.arch || process.arch;
+  let libc = opts.libc;
+  if (platform === "linux" && !libc) libc = getLinuxLibc();
+
+  let preferredPkg = null;
+  let kind = "jar";
+
+  if (platform === "win32") {
+    if (arch === "x64") {
+      preferredPkg = "@appthreat/chennai-windows-amd64";
+      kind = "native";
+    } else {
+      preferredPkg = "@appthreat/chennai-win32-arm64";
+      kind = "jar";
+    }
+  } else if (platform === "darwin") {
+    if (arch === "arm64") {
+      preferredPkg = "@appthreat/chennai-darwin-arm64";
+      kind = "native";
+    } else {
+      preferredPkg = "@appthreat/chennai-darwin-amd64";
+      kind = "jar";
+    }
+  } else if (platform === "linux") {
+    if (arch === "x64") {
+      preferredPkg = libc === "musl"
+        ? "@appthreat/chennai-linux-amd64-musl"
+        : "@appthreat/chennai-linux-amd64";
+      kind = "native";
+    } else if (arch === "arm64") {
+      preferredPkg = libc === "musl"
+        ? "@appthreat/chennai-linux-arm64-musl"
+        : "@appthreat/chennai-linux-arm64";
+      kind = libc === "musl" ? "jar" : "native";
+    }
+  }
+
+  if (!preferredPkg) {
+    preferredPkg = "@appthreat/chennai-jar";
+    kind = "jar";
+  }
+
+  return { preferredPkg, kind, platform, arch, libc };
+}
+
+function readSelfVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(join(SELF_DIR, "package.json"), "utf8")).version;
+  } catch (_) {
+    return undefined;
+  }
+}
+
+function staticGlobalRoots() {
+  const roots = new Set();
+  const env = process.env;
+  if (env.GLOBAL_NODE_MODULES_PATH) roots.add(env.GLOBAL_NODE_MODULES_PATH);
+  const prefix = env.npm_config_prefix || env.PREFIX;
+  if (prefix) {
+    roots.add(join(prefix, "lib", "node_modules"));
+    roots.add(join(prefix, "node_modules"));
+  }
+  const launch = process.argv[1];
+  if (launch) {
+    const binDir = dirname(launch);
+    roots.add(join(binDir, "..", "lib", "node_modules"));
+    roots.add(join(binDir, "node_modules"));
+  }
+  try {
+    const execDir = dirname(process.execPath);
+    roots.add(join(execDir, "..", "lib", "node_modules"));
+    roots.add(join(execDir, "node_modules"));
+  } catch (_) {}
+  return [...roots];
+}
+
+let _queriedGlobalRoots;
+function queriedGlobalRoots() {
+  if (_queriedGlobalRoots) return _queriedGlobalRoots;
+  const roots = new Set();
+  for (const cmd of ["npm root -g", "pnpm root -g"]) {
+    try {
+      const out = execSync(cmd, { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" }).trim();
+      if (out) roots.add(out);
+    } catch (_) {}
+  }
+  _queriedGlobalRoots = [...roots];
+  return _queriedGlobalRoots;
+}
+
+function candidatePackageDirs(pkgName, searchOpts = {}) {
+  const folder = pkgName.split("/")[1];
+  const version = readSelfVersion();
+  const parts = SELF_DIR.split(sep);
+  const dirs = [];
+
+  dirs.push(join(SELF_DIR, "node_modules", "@appthreat", folder));
+
+  for (let i = parts.length - 1; i >= 0; i--) {
+    if (parts[i] === "node_modules") {
+      const root = parts.slice(0, i + 1).join(sep) || sep;
+      dirs.push(join(root, "@appthreat", folder));
+      if (version) {
+        dirs.push(join(root, ".pnpm", `@appthreat+${folder}@${version}`, "node_modules", "@appthreat", folder));
+      }
+    }
+  }
+
+  const pnpmMarker = `${sep}.pnpm${sep}`;
+  const pnpmIdx = SELF_DIR.indexOf(pnpmMarker);
+  if (pnpmIdx !== -1 && version) {
+    const base = SELF_DIR.slice(0, pnpmIdx);
+    dirs.push(join(base, ".pnpm", `@appthreat+${folder}@${version}`, "node_modules", "@appthreat", folder));
+  }
+
+  const globalRoots = staticGlobalRoots();
+  if (searchOpts.includeQueriedGlobals) globalRoots.push(...queriedGlobalRoots());
+  for (const root of globalRoots) {
+    dirs.push(join(root, "@appthreat", folder));
+    if (version) {
+      dirs.push(join(root, ".pnpm", `@appthreat+${folder}@${version}`, "node_modules", "@appthreat", folder));
+    }
+  }
+
+  return [...new Set(dirs)];
+}
+
+export function describeChennaiSearch(opts = {}) {
+  const { preferredPkg, platform, arch, libc } = resolveChennaiProvider(opts);
+  const packagesToTry = [preferredPkg];
+  if (preferredPkg !== "@appthreat/chennai-jar") {
+    packagesToTry.push("@appthreat/chennai-jar");
+  }
+  const attempts = [];
+  for (const pkg of packagesToTry) {
+    const isNative = NATIVE_PACKAGES.has(pkg);
+    for (const pkgDir of candidatePackageDirs(pkg, { includeQueriedGlobals: true })) {
+      const checkPath = isNative
+        ? join(pkgDir, "bin", platform === "win32" ? "chennai.exe" : "chennai")
+        : join(pkgDir, "plugins");
+      attempts.push({ pkg, kind: isNative ? "native" : "jar", path: checkPath, exists: fs.existsSync(checkPath) });
+    }
+  }
+  return { selfDir: SELF_DIR, platform, arch, libc, preferredPkg, attempts };
+}
+
+export function locateChennaiBinary(opts = {}) {
+  const debug = !!process.env.CHENNAI_DEBUG;
+  const { preferredPkg, platform } = resolveChennaiProvider(opts);
+
+  if (debug) {
+    console.error(`[chennai] resolver self dir: ${SELF_DIR}`);
+    console.error(`[chennai] platform=${platform} preferred=${preferredPkg}`);
+  }
+
+  const packagesToTry = [preferredPkg];
+  if (preferredPkg !== "@appthreat/chennai-jar") {
+    packagesToTry.push("@appthreat/chennai-jar");
+  }
+
+  const tryPackage = (pkg, pkgDir) => {
+    const isNative = NATIVE_PACKAGES.has(pkg);
+    const exeName = platform === "win32" ? "chennai.exe" : "chennai";
+    const binaryPath = join(pkgDir, "bin", exeName);
+    if (debug) console.error(`[chennai] check ${binaryPath} -> ${fs.existsSync(binaryPath)}`);
+    if (fs.existsSync(binaryPath)) {
+      const engineName = platform === "win32" ? "chennai-engine.exe" : "chennai-engine";
+      let enginePath = null;
+      if (isNative) {
+        enginePath = join(pkgDir, "bin", engineName);
+        enginePath = fs.existsSync(enginePath) ? enginePath : null;
+      } else {
+        // JAR fallback: engine launcher lives under plugins/bin/
+        const jarEnginePath = join(pkgDir, "plugins", "bin", engineName);
+        enginePath = fs.existsSync(jarEnginePath) ? jarEnginePath : null;
+      }
+      return { kind: isNative ? "native" : "jar", pkg, binPath: binaryPath, enginePath, pkgDir };
+    }
+    return null;
+  };
+
+  for (const includeQueriedGlobals of [false, true]) {
+    for (const pkg of packagesToTry) {
+      for (const pkgDir of candidatePackageDirs(pkg, { includeQueriedGlobals })) {
+        const found = tryPackage(pkg, pkgDir);
+        if (found) return found;
+      }
+    }
+  }
+  return null;
+}