@eyeauras/insight-cli 0.0.0-stage → 0.1.0

package/references/InsightRepositoryProbe.java

@@ -0,0 +1,55 @@
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.Application;
+import ghidra.framework.HeadlessGhidraApplicationConfiguration;
+import ghidra.framework.client.RepositoryAdapter;
+import ghidra.framework.remote.User;
+import com.xebyte.headless.GhidraServerManager;
+import com.google.gson.Gson;
+import java.util.*;
+import java.io.PrintStream;
+
+/** Fixed read-only probe. No write/checkout/terminate operation exists here. */
+class InsightRepositoryProbe {
+  public static void main(String[] args) {
+    PrintStream output = System.out;
+    System.setOut(System.err); // Ghidra diagnostics never share the result protocol.
+    try {
+      if (args.length != 3 || !Set.of("reader", "publisher").contains(args[2])) throw new IllegalArgumentException();
+      Application.initializeApplication(new GhidraApplicationLayout(), new HeadlessGhidraApplicationConfiguration());
+      GhidraServerManager manager = new GhidraServerManager();
+      manager.connect();
+      if (manager.server() == null || !manager.server().isConnected()) throw new IllegalStateException();
+      RepositoryAdapter repository = manager.server().getRepository(args[0]);
+      repository.connect();
+      User user = repository.getUser();
+      if (user == null || !user.getName().equals(System.getenv("GHIDRA_SERVER_USER"))) throw new IllegalStateException();
+      if (args[2].equals("reader") ? !user.isReadOnly() : !user.hasWritePermission()) throw new SecurityException();
+      int split = args[1].lastIndexOf('/');
+      String folder = split == 0 ? "/" : args[1].substring(0, split), name = args[1].substring(split + 1);
+      var item = repository.getItem(folder, name);
+      if(item==null){
+        boolean reserved=repository.fileExists(folder,name);
+        repository.disconnect();manager.server().disconnect();
+        output.println(new Gson().toJson(Map.of("state",reserved?"reserved":"absent","repository",args[0],"path",args[1],"permission",user.getPermissionType())));
+        System.exit(0);
+      }
+      var checkouts = repository.getCheckouts(folder, name);
+      var versions = repository.getVersions(folder, name);
+      if (item == null || checkouts == null || versions == null || versions.length == 0) throw new IllegalStateException();
+      List<Map<String,Object>> history = new ArrayList<>();
+      for (var version : versions) history.add(Map.of("version", version.getVersion(), "comment", version.getComment() == null ? "" : version.getComment()));
+      List<Long> ids = new ArrayList<>();
+      for (var checkout : checkouts) ids.add(checkout.getCheckoutId());
+      var result = new LinkedHashMap<String,Object>();
+      result.put("repository",repository.getName()); result.put("path",(item.getParentPath().equals("/") ? "/" : item.getParentPath() + "/") + item.getName());
+      result.put("version",item.getVersion()); result.put("permission",user.getPermissionType());
+      result.put("checkouts",ids); result.put("checkinActive",repository.isCheckinActive(folder,name)); result.put("versions",history);
+      repository.disconnect(); manager.server().disconnect();
+      output.println(new Gson().toJson(result));
+      System.exit(0);
+    } catch (Throwable error) {
+      output.println("{\"error\":\"authoritative_repository_probe_failed\"}");
+      System.exit(1);
+    }
+  }
+}

package/references/administration.md

@@ -0,0 +1,33 @@
+# Projects, files and server administration
+
+Research uses root session/target scope. `ghidra projects` manages separate projects inside the
+selected profile; these projects do not select or replace an agent's private context. Use an
+explicit `--project` for create/open/close/info/files and file operations. Closing releases the
+native handle and preserves files; deletion requires Destructive. File listings are paged.
+Moves select a source `--path` and an existing `--destination` folder. Existing names are preserved.
+
+`ghidra program export --session <id> --target <id> --output <file>` saves the selected private
+program as GZF without publishing. `ghidra program import --project <name> --input <gzf>
+--path /folder/program` adds that saved program to a managed project. Importing files does not
+change the immutable target's input identity. Export requires a new output file.
+
+`ghidra projects archive --project <name> --output <gar>` exports a native Ghidra project archive.
+`ghidra projects restore --project <new-name> --input <gar>` restores into a new independent owned
+project. Archive entries cannot escape their destination; restoration accepts at most 100,000
+entries and 4 GiB of declared uncompressed data. Research contexts and pending work remain separate.
+
+Changing operations accept `--request-id`. A verified native completion journal can recover a
+lost project response without executing that operation again. If no complete journal exists,
+changing that project stays blocked; read-only inspection remains available. Partial or different
+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
+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.
+Facade reader/publisher authority and canonical publication checkouts remain protected.
+
+Unknown server administration outcomes are retained without blind replay. Server/file effects
+are independent of program merge. Use generated help for flags and Factory profile/secret commands
+for connection configuration.

package/references/archive.md

@@ -0,0 +1,32 @@
+# Exchange private documentation with an archive
+
+Archive exchange is disabled until the selected Factory profile has an explicit `archiveUrl`.
+Use HTTPS for a remote service; local HTTP is supported for local services. URLs cannot contain
+credentials, query parameters or fragments. An optional bearer token is stored with
+`auth login --role archive --password-stdin`; it is a Factory secret and is never passed to
+Ghidra or the debuggee. `auth logout` clears this token as well as external server credentials.
+
+Use `ghidra archive ingest-function --address <entry>` or `ingest-program`, with the usual
+`--session` and `--target`. Both export the selected private view. `--version-label` supplies
+the archive version; its default is `unknown`. Internal project directories are not used as
+version labels. Bulk selection skips default function names unless `--include-default-named`
+is set; `--limit` bounds visited functions. Zero selects all, subject to the documented bound.
+`--dry-run` validates payloads and returns would-be counts without a network request.
+
+The service contract is `POST <archiveUrl>/v1/doc_archive/upsert` with JSON and an optional
+`Authorization: Bearer ...` header. The payload matches the pinned GhidraMCP builder: binary
+name, explicit version, function address, run/tool identity, name/prototype, calling convention,
+flags, matching hash/shape metadata, tags, named locals and instruction comments when present.
+The binary name is the logical target name. Each successful JSON response must contain a
+boolean `created` and a nonnegative integer `conflicts_enqueued`. Redirects are refused.
+
+Results retain created, updated, conflict, skipped and error counts. Archive conflict counts
+describe the external service's decisions; they do not resolve program merge conflicts.
+Use an optional stable `--request-id` when a response might be lost. A repeated ID returns
+the saved successful result or the retained uncertain outcome, without sending again.
+Each outbound payload identity and the source snapshot are retained before dispatch. Unknown
+external outcomes stay observable and do not block unrelated private research. A new request ID
+expresses another explicit submission; the facade does not assume the service can deduplicate it.
+
+Archive requests do not publish the program or alter another session. Developing or deploying
+the external archive service is outside this package; acceptance uses an owned contract fixture.

package/references/artifacts.md

@@ -0,0 +1,47 @@
+# Save ordinary research materials
+
+`insight-cli artifacts save <path> --json` saves a file or a settled directory tree in
+the selected profile's AppData. It needs Factory Update permission and does not require
+Ghidra, Java, authentication, target/session selectors or evidence metadata. Relative input
+paths resolve against the caller's working directory. Use `--help` for generated syntax.
+
+Save existing project files in their existing format; no `notes.md`, `finding.md` or
+`research/` layout is required. The saved copy is a checkpoint and does not replace the
+project's canonical evidence location or its source-of-truth rules.
+
+Write notes and useful external-tool outputs as ordinary files while investigating. When
+the selected files are no longer being edited, save one file, a completed worker subfolder
+or the relevant project folder. For a project without a prescribed layout, for example:
+
+```sh
+insight-cli artifacts save ./research --json
+```
+
+The receipt has `state: "saved"`, `path`, `kind` (`file` or `directory`), `files`, `bytes`
+and `sha256`. `path` points to an ordinary browsable copy with the source basename and
+relative layout. Empty files and empty directories are retained. File count counts regular
+files; byte count counts their contents. A file's SHA-256 hashes its bytes; a directory's
+SHA-256 hashes its canonical manifest of relative paths, kinds, file lengths and hashes.
+The manifest is stored beside the content, outside the returned directory.
+
+The service copies and syncs data before publishing the completed snapshot. Failure does
+not return a successful receipt or expose a partial completed snapshot. Source edits made
+after a successful save do not change the copy. Treat saved copies as retained snapshots;
+edit the original research folder and save a new copy for another checkpoint. Each call
+creates a new saved copy, including a repeated call after a lost response.
+
+Keep a directory stable for the save: detected concurrent edits are rejected. Copying
+several files is not an atomic filesystem snapshot of a directory that other agents keep
+changing. Symbolic links and special files are rejected rather than followed or silently
+omitted. Select the actual intended regular file/directory. Do not save a directory that
+contains the destination materials store. Traversal supports at most 100,000 entries and
+128 levels to bound inventory memory and recursion. Disk/permission failures return nonzero.
+
+The saved bytes establish what was retained. Commands, tool versions and interpretations
+written in a note remain the author's statements, not execution attestations. No upload,
+tool execution or Ghidra publication is performed by saving materials.
+
+Profile deletion/configuration invalidation is blocked while retained materials exist,
+as with retained research work. Close tool contexts normally; preserve snapshots separately
+if retiring a profile. There is no automatic registration, cleanup policy, graph database
+or additional read API: read the receipt's path with normal file tools.

package/references/debugger.md

@@ -0,0 +1,40 @@
+# Debug an input in its private context
+
+Use the same `--session` and `--target` as static research. `debugger launch-offers` lists
+available launchers and starts the owned GUI services when needed. `debugger launch` executes a
+verified copy of the selected immutable input in an owned run directory. It accepts `--offer`,
+`--args`, `--cwd`, a bounded launch timeout and the optional request ID. A second live process
+uses another session; it does not replace this context's current process.
+
+Read `debugger status`, `modules`, `registers`, `stack-trace` and `traces`. Address conversion
+uses `static-to-dynamic` and `dynamic-to-static`; memory and breakpoint commands take dynamic
+addresses. Lists are paged. Read results identify the logical context and current trace, and
+report whether the trace is connected or retained after disconnection. `--trace` selects a
+saved trace within this context; IDs from another context are rejected.
+
+Changing commands include interrupt, resume, step into/over/out and breakpoint set/remove.
+Their optional request ID retrieves the recorded result without executing again. A genuinely
+unknown CPU action remains uncertain; a later program counter alone does not prove how many
+instructions executed. Read-only observation remains available for uncertain debugger actions.
+Program merge does not roll back execution, debugger I/O or other process side effects.
+
+Trace databases are checkpointed separately from the private program and verified by independent
+packed-database readback before acknowledgment. Reopening after process replacement restores
+saved trace data as disconnected. It does not restart the debuggee or reconstruct CPU execution.
+Ordinary static program edits remain private and retain the usual merge/refresh behavior.
+Static breakpoint bookmarks created by debugger actions also count as pending program changes.
+They follow explicit merge/refresh and complex-change conflict rules; CPU execution does not
+wait for publication, and publishing a program never resumes another session's process.
+
+On macOS, launch enforces the selected working directory, including paths with spaces and
+quotes. A GUI backend crash ends the owned live debuggee through its debugger controller.
+Verified trace data retained before a lost action response is adopted on disconnected continuation,
+unless a later observation already saved a newer view. The CPU action itself remains uncertain.
+
+On macOS, use an installed local LLDB and an executable supported by that host. GUI startup
+prepares the Python wheels already supplied with Ghidra in owned storage; it does not install
+packages into system Python. A launcher's optional Python executable and Windows debugger
+directory are Factory profile settings. Native Windows/Linux acceptance remains deferred.
+
+Use generated help for exact flags. A retained static breakpoint bookmark may remain after its live trace placement is
+removed; `trace_location_count` distinguishes current placements from that static metadata.

package/references/extensions-and-sync.md

@@ -0,0 +1,124 @@
+# Managed extensions and synchronization
+
+`insight-cli` keeps targets/sessions above tools. Both features below belong to the Ghidra
+context/runtime selected by the existing profile; they introduce no new agent/session objects.
+The Factory API uses the same command paths and options as these CLI examples.
+
+## Consume a ready-built SDK extension
+
+Use an unpacked standard Ghidra 12.1.2 extension module, with `Module.manifest` and
+`extension.properties` at its root. Directory basename and property `name` must agree.
+The module can contain compiled `lib/*.jar`, `data/languages` (including compiled Sleigh `.sla`,
+`.ldefs`, `.pspec`, `.cspec`) and `ghidra_scripts`. Build the extension with its own upstream
+SDK build before consumption. ZIP acquisition/extraction, dependency resolution, building a
+third-party extension and publishing extensions are outside this local management contract.
+
+```sh
+insight-cli ghidra extensions inspect --directory ./MyExtension --json
+insight-cli ghidra extensions install --directory ./MyExtension --sha256 <content-sha256> --json
+insight-cli ghidra extensions list --json
+```
+
+Inspect computes the content identity without executing extension code. Install requires the
+`Destructive` permission, consumes all regular files into profile storage and verifies the
+copy. It never edits the installed SDK or depends on the original directory after consumption.
+The identity covers sorted relative paths, SHA256 and size for every file; it is not a ZIP hash.
+Symlinks/special files, hidden/traversing paths and incompatible version metadata reject.
+Limits: 32 modules/profile, 8192 files and 256 MiB/module, 16 path components.
+A name stays pinned to one content identity; different builds use different module names or profiles.
+
+```sh
+insight-cli ghidra extensions disable --name MyExtension --json
+insight-cli ghidra extensions enable --name MyExtension --json
+```
+
+Stop the Factory IPC owner after changing the enabled set, then run the next ordinary command.
+A running owner refuses changed runtime configuration. Immutable module copies remain retained
+when disabled, so saved contexts can resume with their original language/type dependencies after
+re-enabling. Existing private work and unknown request/publication journals are preserved.
+Disabling the language required by a saved program does not convert that program to another language.
+Enablement/install are desired-state/content operations; repeating the same input is idempotent.
+No automatic extension updates or network/package-manager installation occur.
+
+Discover what the installed SDK actually provides:
+
+```sh
+insight-cli ghidra extensions capabilities --kind languages --filter MyProcessor --json
+insight-cli ghidra extensions capabilities --kind analyzers --filter MyExtension --json
+insight-cli ghidra extensions capabilities --kind plugins --filter MyExtension --json
+```
+
+These paged inventories return actual native IDs (and compiler IDs for languages); `managed`
+on analyzer/plugin classes identifies consumed modules. Select a language/compiler using
+`ghidra open --language <id> --compiler-spec <id>`. Use `analysis configure-analyzer --name <name>
+--enabled true` and `analysis reanalyze` in an explicit context. Program writes remain complex
+private changes and follow the existing saved-state verification/merge rules.
+Extension scripts have explicit inventory IDs such as `extension:MyExtension/Example.java`;
+run that ID through `scripts run`, never guess a process-global search path.
+
+For a GUI plugin, use `ghidra plugins set --plugin <class-id> --enabled true|false` with
+`--session` and `--target`. `plugins list` returns enabled managed plugins in that owned GUI tool.
+Only classes from enabled managed modules can be toggled. Enablement is read back immediately;
+its lifetime is the current GUI tool, rather than a promise to resurrect it after a crash.
+Plugin constructors/disposal may change program state: the operation saves a private snapshot
+and conservatively records a complex change. An uncertain effect is never replayed; close the
+owned context when its live effect cannot be established. Configuration dialogs, arbitrary
+plugin-specific option schemas, native libraries with platform installers and hot class unloading
+are not promised by this module contract; the explicit script API remains available.
+
+Extension code runs with the OS privileges of the owned JVM. Digest pinning establishes which
+code runs, not a security sandbox or a guarantee of third-party compatibility. Workers, GUI,
+inspection and publication helpers use the same verified enabled set. The storage-only local
+Ghidra Server continues to use the pinned base SDK and does not run managed analysis plugins.
+
+## Optional synchronization for one context
+
+The default remains explicit `merge` and `refresh`. Reads keep the private view. Configure an
+existing `(session, target, ghidra)` context explicitly:
+
+```sh
+insight-cli ghidra sync-policy get --session s_a --target t_exe --json
+insight-cli ghidra sync-policy set --session s_a --target t_exe \
+  --publish after-edit --refresh before-edit --json
+```
+
+| Setting | Behavior |
+| --- | --- |
+| `--publish manual` | Local edits and saves do not publish automatically. |
+| `--publish after-edit` | After a supported program edit has a verified saved acknowledgment, merge all pending work in that context. Also publishes pending work on explicit `ghidra save`. |
+| `--publish after-save` | Ordinary edits stay private; explicit scoped `ghidra save` merges all pending work after saving. |
+| `--refresh manual` | No automatic incoming update. |
+| `--refresh before-edit` | Refresh before a program-edit command; any returned conflict stops that edit before dispatch. Safe incoming changes from the refresh remain retained. |
+
+Supported program-edit commands include ordinary names/comments, types, bytes/assembly,
+analysis and scripts. Policy excludes control commands (`open`, `close`, `merge`, `refresh`,
+policy/discard), cross-target transfer, GUI/debugger, archive/project/server operations, file
+exports, library databases and Version Tracking. Session-wide `save-all` saves privately;
+use scoped `save` for automatic publication. Read-only queries never trigger refresh/publication.
+Automatic refresh/publication also requires the current Factory `Update` permission, including
+when the edit itself is gated by `Destructive`. Revocation prevents starting those automatic
+effects; retrieval of a completed workflow does not repeat them. No background timers, watchers
+or automatic semantic conflict resolution are introduced.
+
+A successful automatic edit includes its normal local result plus `automatic.refresh` and/or
+`automatic.publication`, final `pendingChanges` and `sharedState`. After a publication conflict,
+the command fails with `state: conflict`, `localApplied: true` and the retained `local` result.
+Nothing from that merge is published. An incoming conflict reports `phase: refresh` and
+`localApplied: false`; the requested edit was not started. Lost local replies may report
+`localOutcome: unknown`; they do not falsely assert that the local effect failed.
+
+Automatic merge uses exactly the manual contract: any conflict prevents the whole publication;
+only verified scalar categories combine after divergence; complex divergence retains both
+versions. Use explicit refresh, inspect/resolve scalar conflicts, or transfer complex changes
+onto a current base. A failed automatic workflow does not silently retry after resolution;
+use a new request or explicit merge for the new intention.
+
+Policy survives owner replacement. Optional request IDs (up to 128 characters) bind the local edit, incoming refresh and publication workflow. Repeating the same ID/input
+retrieves its result or reconciles the original publication; it never replays a check-in or
+uncertain script. The original workflow keeps its original policy even if policy changes later.
+Retrying an earlier manual edit does not retroactively publish it after enabling automatic mode.
+Without a request ID, a call is a new intention, as elsewhere in the facade.
+
+The caller ID reserves the complete automatic workflow in the common profile namespace, even
+when incoming conflicts prevent the local command from starting. It cannot be reused by an
+explicit merge, close, export or administration operation. Internal child effects have derived IDs.