@eyeauras/insight-cli 0.1.0 → 0.2.0

package/references/administration.md

@@ -22,7 +22,8 @@ changing that project stays blocked; read-only inspection remains available. Par
 export output does not prove success and is preserved. Retain receipts for continuation.
 
 `ghidra server` operates on the configured local or external server. `status` reports connection
-state; `connect` enables shared operations; `disconnect` releases the owned local server or the
+state, including a missing runtime before installation; `start/stop` manage the owned local
+server (stop requires closed contexts). `connect` enables shared operations; `disconnect` releases the owned local server or the
 external connection. Reconnect preserves repositories. Repository/file/history/checkout commands
 require the explicit repository and relevant path. Admin actions require actual server authority
 alongside Factory permissions. Changing ACLs preserves other users and anonymous access.

package/references/managed-runtime.md

@@ -0,0 +1,116 @@
+# Managed Ghidra runtime
+
+Use `ghidra install` for a complete compatible installation. Node 24+ is the bootstrap dependency;
+no existing Java, Ghidra, Homebrew, Gradle, compiler or Python MCP bridge is required. Factory
+profiles, permissions and OS secret storage remain in use. Follow the project's tool rules when
+it specifies an external installation or server.
+
+```sh
+insight-cli profile create local
+insight-cli --profile local permissions grant Update
+insight-cli --profile local ghidra install
+insight-cli --profile local ghidra status
+insight-cli --profile local ghidra open ./client.exe --session new --json
+```
+
+`download` caches the complete pinned Ghidra/JDK archives, without selecting or starting a runtime.
+`install` uses that cache or downloads missing archives, unpacks to a new stage, checks JDK 21 and
+Ghidra 12.1.2, decompiles a known x86 function and starts a disposable local Ghidra Server. The
+server probe authenticates its identity and reader/publisher permissions. Selection changes only
+after all checks pass. The bridge and helper sources come from the version-matched npm package.
+A failed install preserves its stage/diagnostics and the old selection. Retrying uses a fresh stage;
+completed cached archives are reused. A later install/doctor/uninstall authenticates and stops
+any leftover disposable probe server before proceeding; an unverified live identity blocks recovery. Interrupted partial downloads are never used as complete files.
+
+`status` without scope is passive: selection, paths, missing components, installations, retained
+stages, recorded checks and live process receipts. It works before installation. It does not start
+Java or create a research workspace. `status --session S --target T` retains the scoped live health
+check. `server status` also works without an installed runtime and explains missing prerequisites.
+`doctor` explicitly runs disposable native decompiler/server probes and checks macOS LLDB Python.
+It never imports a research target or publishes research changes. Readiness recorded by a doctor
+run includes its runtime fingerprint; status identifies whether that record matches the selection.
+
+## Local archives and external installations
+
+```sh
+insight-cli --profile local ghidra download
+insight-cli --profile local ghidra install --offline
+insight-cli --profile local ghidra install --archive ./ghidra.zip
+insight-cli --profile local ghidra install --archive ./ghidra.zip \
+  --java-archive ./jdk.tar.gz --offline
+insight-cli --profile local ghidra install --executable /tools/ghidra/ghidraRun
+insight-cli --profile local ghidra install --executable /tools/ghidra \
+  --java /tools/jdk/bin/java --offline
+```
+
+`--executable` accepts the actual Ghidra launcher (`ghidraRun[.bat]`, or
+`support/analyzeHeadless[.bat]`) or installation directory. It needs the complete compatible
+installation, including host native components. A target EXE is not a Ghidra launcher.
+Common Homebrew launcher wrappers are resolved through the adjacent complete `libexec` tree.
+The external Ghidra tree is never modified or deleted. Java is delivered automatically unless
+`--java` or `--java-archive` is supplied. Legacy profile `java`/`ghidraHome` configuration still works
+when no explicit selection exists; an explicit selection takes precedence and never silently
+falls back to profile paths after failure or uninstall.
+
+Local archives are caller-selected inputs, consumed into owned hash-addressed copies before
+extraction so later source edits cannot change the installed bytes. Optional `--archive-sha256` and
+`--java-archive-sha256` check the expected bytes; the actual digests are recorded in the installation
+identity. `--offline` prohibits network acquisition: provide/cache every required archive. On macOS,
+an official Ghidra zip also needs the pinned prebuilt native archive in cache. The managed macOS
+distribution already includes these natives. Executable modes are preserved; paths, links and
+expanded sizes are checked during portable Node extraction. Downloads use pinned SHA256 values.
+No external unzip, tar or Python executable is needed for extraction.
+
+## Server, process and data ownership
+
+The Ghidra distribution includes Ghidra Server. It uses the selected JDK and immutable tool code;
+its repository, certificates, credentials and process settings are separate profile data.
+Ordinary `open` starts it automatically. `server start` explicitly starts/enables it, and
+`server stop` stops the identified owned server after all contexts are closed. It refuses to stop
+a server under live clients. A later open can start it again; explicit `disconnect` disables shared
+operations until `connect`/`start`. `server connect/disconnect` retain their connection-management API.
+An external server remains configured through profile server/repository/account fields and Factory
+secrets; `server stop` cannot stop that external service.
+
+Code/cache/installation receipts live under profile AppData `runtime/`; research remains under
+`workspace/`, and saved files under `materials/`. One selected immutable installation serves many
+isolated JVM contexts; each has its own projects, home, settings, cache/temp and authenticated
+endpoint. No per-agent copy of the Ghidra code distribution is required. This is process and data
+isolation; it does not restrict arbitrary user scripts to an OS security sandbox.
+
+Close scoped contexts and stop the owned server before selecting/reinstalling/removing a runtime.
+A live receipt conservatively blocks these operations; it never authorizes killing a PID.
+Download and doctor can run without switching the current runtime. Runtime commands serialize
+within the Factory owner. Changing a selected runtime invalidates cached backend handles, without
+removing saved research. There is no automatic version migration or floating upstream upgrade.
+
+```sh
+insight-cli --profile local ghidra close --session S --target T
+insight-cli --profile local ghidra server stop
+insight-cli --profile local permissions grant Destructive
+insight-cli --profile local ghidra uninstall
+# Optional cache deletion; research and external installations remain preserved:
+insight-cli --profile local ghidra uninstall --purge-cache
+```
+
+Uninstall removes only selected owned installation files. It preserves the selection as an
+uninstalled receipt, so later research reports a missing runtime instead of changing bindings.
+Archives remain reusable unless `--purge-cache` is selected. Reinstalling the same archives restores
+the same runtime identity. Sessions, private snapshots, unresolved publication journals, server
+repositories and artifacts survive. Uninstall does not resolve an uncertain merge or replay it.
+
+## Sources and host boundary
+
+The catalog pins Ghidra 12.1.2 and Temurin JDK 21.0.11+10. macOS uses public Homebrew-built Ghidra
+bottles with native components (macOS 14+, ARM64 or x64); no installed Homebrew is used. Linux x64
+and Windows x64 use the official Ghidra zip and Temurin archive. All source URLs, hashes and license
+identities are in `src/runtime-catalog.ts`; downloaded distributions retain their license files.
+Unsupported platforms fail explicitly and may use compatible external profile paths. Native
+acceptance for this delivery is macOS ARM64; catalog availability is not Windows/Linux native proof.
+
+The host provides Node/npm, OS frameworks, display/keychain access and debugger authorization.
+macOS LLDB and its embedded Python come from Apple's developer tools; they are OS prerequisites,
+not downloaded third-party Python dependencies. `doctor` reports a missing host debugger as a partial
+failure even when static analysis/server pass. No root installation, developer-tools installer,
+Gatekeeper disabling, shell-profile edit or global Java/Python selection is performed. Ghidra GUI
+agents receive private copies of the Ghidra SDK's pinned debugger Python wheels.

package/references/native/InsightRuntimeDoctor.java

@@ -0,0 +1,33 @@
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.*;
+import ghidra.program.database.ProgramDB;
+import ghidra.program.model.lang.LanguageID;
+import ghidra.program.util.DefaultLanguageService;
+import ghidra.program.flatapi.FlatProgramAPI;
+import ghidra.app.decompiler.DecompInterface;
+import ghidra.util.task.TaskMonitor;
+import java.io.ByteArrayInputStream;
+
+/** Disposable native probe: decode and decompile a known function using the selected installation. */
+class InsightRuntimeDoctor {
+ public static void main(String[] args) {
+  var out=System.out;System.setOut(System.err);
+  try {
+   Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+   var language=DefaultLanguageService.getLanguageService().getLanguage(new LanguageID("x86:LE:32:default"));
+   var program=new ProgramDB("runtime-probe",language,language.getDefaultCompilerSpec(),new Object());
+   var consumer=new Object();program.addConsumer(consumer);
+   int tx=program.startTransaction("probe");
+   var start=program.getAddressFactory().getDefaultAddressSpace().getAddress(0x1000);
+   program.getMemory().createInitializedBlock(".text",start,new ByteArrayInputStream(new byte[]{(byte)0xb8,42,0,0,0,(byte)0xc3}),6,TaskMonitor.DUMMY,false);
+   var api=new FlatProgramAPI(program);api.disassemble(start);var function=api.createFunction(start,"runtime_probe");
+   program.endTransaction(tx,true);
+   var decompiler=new DecompInterface();
+   if(!decompiler.openProgram(program))throw new IllegalStateException("Decompiler did not open program");
+   var result=decompiler.decompileFunction(function,30,TaskMonitor.DUMMY);
+   if(!result.decompileCompleted()||result.getDecompiledFunction()==null||!result.getDecompiledFunction().getC().contains("0x2a"))throw new IllegalStateException("Native decompile did not produce the expected return value");
+   decompiler.dispose();program.release(consumer);
+   out.println("{\"state\":\"ready\",\"headless\":true,\"decompiler\":true,\"expectedReturn\":42}");System.exit(0);
+  } catch(Throwable failure){failure.printStackTrace(System.err);out.println("{\"state\":\"failed\"}");System.exit(1);}
+ }
+}

package/references/setup.md

@@ -1,7 +1,9 @@
 # Setup
 
-Use Node 24+, Ghidra 12.1.2 and a Java 21 JDK. Configure the runtime with Factory's profile
-commands and generated help: `java` and `ghidraHome` select installed dependencies.
+Use Node 24+ and `ghidra install` to deliver Ghidra 12.1.2, JDK 21, native components and
+server support. See [managed runtime](managed-runtime.md) for download/install/offline archives,
+external executable paths, status/doctor and safe removal. Existing Factory profile `java` and
+`ghidraHome` paths remain supported when no managed/external selection exists.
 The package contains the verified GhidraMCP 7.0.0 bridge, its Apache-2.0 license/notice and
 artifact provenance. Its pinned functionality catalog is from source
 `57e37a8bf388b1279cff46378f85be1554548f61`, with SHA256

package/skills/insight-re/SKILL.md

@@ -3,7 +3,7 @@ name: insight-re
 description: Investigate shipped programs and binary artifacts with insight-cli and other available tools; retain ordinary research files, coordinate independent agents and publish Ghidra annotations. Use for reverse engineering behavior, not ordinary source-repository browsing.
 ---
 
-# Insight RE 0.1.0
+# Insight RE 0.2.0
 
 Answer the user's research question with inspectable materials. Agents choose the
 investigation; insight-cli supplies applications such as `ghidra` and `artifacts`.