reverseport 0.0.0-stage → 1.2.0

package/dist/cli-runtime/workflowInputError-26EGiDpx.js

@@ -0,0 +1,26 @@
+import { __esmMin } from "./rolldown-runtime-DXoylpqc.js";
+import { AnalysisInputError, init_analysisErrorCore } from "./providerOperationHealth-DSTcYPJe.js";
+import { analysisInputErrorFromIssues, init_inputIssueProjection } from "./reconstructionObligationLedgerSchemas-dvp6PEnZ.js";
+import { z } from "zod";
+
+//#region dist/application/workflowInputError.js
+var requestInputError, workflowInputError;
+function init_workflowInputError() {
+	return (init_workflowInputError = __esmMin((() => {
+		init_analysisErrorCore();
+		init_inputIssueProjection();
+		requestInputError = (operation, cause, input) => analysisInputErrorFromIssues(operation, cause.issues, input, { cause });
+		workflowInputError = (operation, cause) => new AnalysisInputError(operation, { cause }, cause instanceof z.ZodError ? cause.issues.map((issue) => ({
+			path: [],
+			reason: "invalid_value",
+			message: `A nested value failed validation at ${issue.path.length === 0 ? "its root" : issue.path.map(String).join(".")}: ${issue.message}`
+		})) : [{
+			path: [],
+			reason: "invalid_value",
+			message: cause.message
+		}]);
+	})))();
+}
+
+//#endregion
+export { init_workflowInputError, requestInputError, workflowInputError };

package/dist/cli.js

@@ -0,0 +1,91 @@
+import { registerWasmCommands } from "./cli/wasmCommands.js";
+import { snapshotEnvironment } from "./process/snapshotEnvironment.js";
+import { createDirectAnalysis } from "./composition/directAnalysis.js";
+import { registerEvmCommands } from "./cli/evmCommands.js";
+import { registerGoCommands } from "./cli/goCommands.js";
+import { registerAnalysisViewCommands } from "./cli/analysisViewCommands.js";
+import { registerBinaryDiagnosticsCommands } from "./cli/binaryDiagnosticsCommands.js";
+import { Cli } from "incur";
+import { createLogger, parseLogLevel } from "./logger.js";
+import { PRODUCT_IDENTITY } from "./identity.js";
+import { npxRegistrationCommand } from "./application/ClientRegistrationIdentity.js";
+import { registerSetupCommands } from "./cli/setupCommands.js";
+import { registerCoreAnalysisCommands } from "./cli/coreAnalysisCommands.js";
+import { registerUtilityCommands } from "./cli/utilityCommands.js";
+import { registerArtifactCommands } from "./cli/artifactCommands.js";
+import { registerManagedCommands } from "./cli/managedCommands.js";
+import { registerFirmwareCommands } from "./cli/firmwareCommands.js";
+import { registerAndroidCommands } from "./cli/androidCommands.js";
+import { registerApktoolCommands } from "./cli/apktoolCommands.js";
+import { registerJebCommands } from "./cli/jebCommands.js";
+import { registerAdbCommands } from "./cli/adbCommands.js";
+import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
+import { registerProcessCommands } from "./cli/processCommands.js";
+import { registerBrowserCommands } from "./cli/browserCommands.js";
+import { registerWebScriptCommands } from "./cli/webScriptCommands.js";
+import { registerWebModuleCommands } from "./cli/webModuleCommands.js";
+import { registerWebSourceLocationCommands } from "./cli/webSourceLocationCommands.js";
+import { registerWebRuntimeCommands } from "./cli/webRuntimeCommands.js";
+import { registerWebNetworkCaptureCommands } from "./cli/webNetworkCaptureCommands.js";
+import { registerJavaScriptRecoveryCommands } from "./cli/javascriptRecoveryCommands.js";
+import { registerAdvancedBrowserCommands } from "./cli/browserAdvancedCommands.js";
+import { registerBrowserScenarioCommands } from "./cliBrowserScenarioCommands.js";
+import { registerElectronCommands } from "./cli/electronCommands.js";
+import { registerJavaScriptRuntimeObservationCommands } from "./cliJavaScriptRuntimeCommands.js";
+import { registerApplicationCommands } from "./cli/applicationCommands.js";
+import { presentOmittableDefaults } from "./cli/omittableDefaults.js";
+import { streamCliCommandResults, } from "./cli/streamedJsonOutput.js";
+/**
+ * Build the one-shot Incur CLI without starting Hopper at import time.
+ * Analysis commands acquire and close their own sessions; bare `mcp` and
+ * `--mcp` are intercepted by the executable dispatcher before this module loads.
+ */
+export const createCli = (selectedEnvironment = process.env, resultOutput) => {
+    const environment = snapshotEnvironment(selectedEnvironment);
+    const analysis = createDirectAnalysis(environment);
+    const logger = createLogger("cli", environment.REA_LOG_LEVEL === undefined
+        ? "silent"
+        : parseLogLevel(environment.REA_LOG_LEVEL));
+    const cli = Cli.create(PRODUCT_IDENTITY.cliBinary, {
+        version: PRODUCT_IDENTITY.packageVersion,
+        description: "Reverse engineer anything from your terminal or agent.",
+        mcp: {
+            command: npxRegistrationCommand().join(" "),
+            instructions: "Ask what software, artifact, protocol, or behavior the user wants to understand, then choose the available investigation capabilities that can produce evidence.",
+        },
+        sync: false,
+    });
+    registerSetupCommands(cli, logger, environment);
+    registerCoreAnalysisCommands(cli, logger, analysis.runDirectAnalysis);
+    registerUtilityCommands(cli, logger, environment, analysis);
+    registerWasmCommands(cli, logger, environment);
+    registerEvmCommands(cli, logger, environment);
+    registerGoCommands(cli, logger);
+    registerArtifactCommands(cli, logger, analysis.runProviderAnalysis);
+    registerManagedCommands(cli, logger, analysis.runProviderAnalysis);
+    registerAndroidCommands(cli, logger, environment);
+    registerApktoolCommands(cli, logger, environment);
+    registerJebCommands(cli, logger, environment);
+    registerAdbCommands(cli, logger, environment);
+    registerFirmwareCommands(cli, logger, environment);
+    registerBinaryDiagnosticsCommands(cli, logger, environment);
+    registerAnalysisViewCommands(cli, logger);
+    registerEvidenceCommands(cli, logger);
+    registerProcessCommands(cli, logger, environment);
+    registerBrowserCommands(cli, logger);
+    registerWebScriptCommands(cli, logger);
+    registerWebModuleCommands(cli, logger, environment);
+    registerWebSourceLocationCommands(cli, logger, environment);
+    registerWebRuntimeCommands(cli, logger);
+    registerWebNetworkCaptureCommands(cli, logger, environment);
+    registerJavaScriptRecoveryCommands(cli, logger, environment);
+    registerAdvancedBrowserCommands(cli, logger);
+    registerBrowserScenarioCommands(cli, logger, environment);
+    registerElectronCommands(cli, logger, environment);
+    registerJavaScriptRuntimeObservationCommands(cli, logger);
+    registerApplicationCommands(cli, logger);
+    presentOmittableDefaults(cli);
+    if (resultOutput !== undefined)
+        streamCliCommandResults(cli, resultOutput);
+    return cli;
+};

package/dist/cliBrowserContext.js

@@ -0,0 +1,11 @@
+import { createBrowserObservationProvider } from "./composition/browserObservation.js";
+import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
+/** Build the passive browser provider; scope is supplied on each request. */
+export const browserContext = () => ({
+    provider: createBrowserObservationProvider(),
+});
+/** Project a browser operation failure consistently across CLI command groups. */
+export const browserCliError = (error) => ({
+    error: "Browser observation failed",
+    ...projectAnalysisError(error),
+});

package/dist/cliBrowserScenarioCommands.js

@@ -0,0 +1,73 @@
+import { Cli } from "incur";
+import { z } from "zod";
+import { captureBrowserScenario } from "./application/BrowserScenarioCaptureService.js";
+import { withCommandCancellation } from "./cli/commandCancellation.js";
+import { CLI_COMMANDS } from "./cliCommandNames.js";
+import { parseCliJsonInput, resolveCliJsonPaths } from "./cliJsonInput.js";
+import { logCliCommand } from "./cliLogging.js";
+import { AnalysisInputError } from "./domain/analysisErrorCore.js";
+import { AnalysisError } from "./domain/analysisErrorBase.js";
+import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
+import { BrowserObservationError } from "./domain/browserObservationError.js";
+import { projectInputIssues } from "./domain/inputIssueProjection.js";
+import { browserScenarioSchema } from "./domain/browserScenario.js";
+const OPERATION = "capture_browser_scenario";
+/** Register the one-shot controlled browser scenario command. */
+export const registerBrowserScenarioCommands = (cli, logger, environment) => {
+    cli.command(CLI_COMMANDS.captureBrowserScenario, {
+        description: "Run one bounded Playwright browser scenario and return Evidence",
+        args: z.object({
+            inputJson: z
+                .string()
+                .describe("Inline browser scenario JSON or JSON file path"),
+        }),
+        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.captureBrowserScenario, async () => {
+            const input = await parseCliJsonInput(args.inputJson, OPERATION);
+            if (!input.ok)
+                return input.error;
+            const scenario = browserScenarioSchema.safeParse(resolveCliJsonPaths(input.value, [["browser", "executable_path"]]));
+            if (!scenario.success)
+                return cliError(new AnalysisInputError(OPERATION, { cause: scenario.error }, projectInputIssues(scenario.error.issues, input.value)));
+            // Load Playwright only for this command, not during CLI startup.
+            const { createBrowserScenarioProvider } = await import("./composition/browserScenario.js");
+            const provider = createBrowserScenarioProvider(environment);
+            let result;
+            try {
+                result = await captureBrowserScenario(provider, scenario.data, {
+                    signal,
+                });
+                return result.ok ? result.value : cliError(result.error);
+            }
+            finally {
+                try {
+                    await provider?.close?.();
+                }
+                catch (cause) {
+                    // Failed captures already retain their primary error and partial
+                    // observations. A cleanup retry must not replace that outcome.
+                    if (result?.ok)
+                        throw new BrowserObservationError(OPERATION, "cleanup_failed", {
+                            cause,
+                            cleanup: cause instanceof AnalysisError &&
+                                cause.cleanup !== undefined
+                                ? cause.cleanup
+                                : {
+                                    reason: cause instanceof Error
+                                        ? cause.message
+                                        : String(cause),
+                                    resources: cause instanceof AnalysisError &&
+                                        cause.cleanupResources.length > 0
+                                        ? cause.cleanupResources
+                                        : ["browser_transport"],
+                                },
+                            partialObservation: result.value,
+                        });
+                }
+            }
+        })),
+    });
+};
+const cliError = (error) => ({
+    error: "Browser scenario capture failed",
+    ...projectAnalysisError(error),
+});

package/dist/cliCommandNames.js

@@ -0,0 +1,205 @@
+/** Canonical names used by every one-shot CLI command registration. */
+export const CLI_COMMANDS = Object.freeze({
+    inspectWasmArtifact: "inspect-wasm-artifact",
+    inspectEvmInterface: "inspect-evm-interface",
+    inspectWebNetworkCapture: "inspect-web-network-capture",
+    observeWebExecution: "observe-web-execution",
+    inspectWebEventListeners: "inspect-web-event-listeners",
+    traceWebSourceLocation: "trace-web-source-location",
+    traceWebModuleImports: "trace-web-module-imports",
+    analyze: "analyze",
+    inspect: "inspect",
+    decompile: "decompile",
+    setup: "setup",
+    doctor: "doctor",
+    uninstall: "uninstall",
+    update: "update",
+    xrefs: "xrefs",
+    trace: "trace",
+    traceNativeUiAction: "trace-native-ui-action",
+    inspectNativeDispatchMetadata: "inspect-native-dispatch-metadata",
+    capabilities: "capabilities",
+    providers: "providers",
+    function: "function",
+    annotateNativeFunction: "annotate-native-function",
+    inspectNativeApi: "inspect-native-api",
+    instructions: "instructions",
+    search: "search",
+    importReferenceSource: "import-reference-source",
+    inspectArtifact: "inspect-artifact",
+    extractArtifact: "extract-artifact",
+    decodeInterfaceBuilder: "decode-interface-builder",
+    inspectKeyedArchive: "inspect-keyed-archive",
+    traceDylibResolution: "trace-dylib-resolution",
+    inspectNativeDataType: "inspect-native-data-type",
+    inspectNativeLoadImage: "inspect-native-load-image",
+    readBytes: "read-bytes",
+    addressToFileOffset: "address-to-file-offset",
+    traceNativeValues: "trace-native-values",
+    inspectNativeInstruction: "inspect-native-instruction",
+    resolveNativeCallTargets: "resolve-native-call-targets",
+    inspectAssetCatalog: "inspect-asset-catalog",
+    inspectManagedArtifact: "inspect-managed-artifact",
+    inspectRecordedCrash: "inspect-recorded-crash",
+    inspectBinaryLayout: "inspect-binary-layout",
+    inspectGoBinary: "inspect-go-binary",
+    inspectPeResources: "inspect-pe-resources",
+    inspectAnalysisView: "inspect-analysis-view",
+    inspectEvidenceBundle: "inspect-evidence-bundle",
+    inspectFirmwareRegions: "inspect-firmware-regions",
+    extractFirmware: "extract-firmware",
+    inspectAndroidPackage: "inspect-android-package",
+    inspectApktoolClient: "inspect-apktool-client",
+    decodeAndroidResources: "decode-android-resources",
+    inspectAdbClient: "inspect-adb-client",
+    listAdbDevices: "list-adb-devices",
+    inspectAdbDevice: "inspect-adb-device",
+    listAdbPackages: "list-adb-packages",
+    pullAdbPackage: "pull-adb-package",
+    readAdbLogcat: "read-adb-logcat",
+    inspectAdbPackage: "inspect-adb-package",
+    pullAdbFile: "pull-adb-file",
+    pushAdbFile: "push-adb-file",
+    captureAdbScreen: "capture-adb-screen",
+    listAdbProcesses: "list-adb-processes",
+    listAdbDirectory: "list-adb-directory",
+    listAdbFeatures: "list-adb-features",
+    listAdbServices: "list-adb-services",
+    inspectAdbDisplay: "inspect-adb-display",
+    inspectAdbWindow: "inspect-adb-window",
+    readAdbSetting: "read-adb-setting",
+    collectAdbBugreport: "collect-adb-bugreport",
+    resolveAdbPackages: "resolve-adb-packages",
+    installAdbPackage: "install-adb-package",
+    uninstallAdbPackage: "uninstall-adb-package",
+    startAdbApp: "start-adb-app",
+    startAdbActivity: "start-adb-activity",
+    stopAdbApp: "stop-adb-app",
+    searchAndroidClasses: "search-android-classes",
+    inspectAndroidClass: "inspect-android-class",
+    inspectAndroidMethod: "inspect-android-method",
+    traceAndroidReferences: "trace-android-references",
+    inspectJebClient: "inspect-jeb-client",
+    openJebProject: "open-jeb-project",
+    listJebUnits: "list-jeb-units",
+    decompileJebItem: "decompile-jeb-item",
+    inspectManagedMembers: "inspect-managed-members",
+    inspectManagedNativeBoundaries: "inspect-managed-native-boundaries",
+    compareManagedMembers: "compare-managed-members",
+    verifyManagedNativeBoundaries: "verify-managed-native-boundaries",
+    importManagedReconstruction: "import-managed-reconstruction",
+    projectManagedApplicationGraph: "project-managed-application-graph",
+    observeNativeUi: "observe-native-ui",
+    observeNativeCalls: "observe-native-calls",
+    captureNativeUiScenario: "capture-native-ui-scenario",
+    inspectMacho: "inspect-macho",
+    inspectSignature: "inspect-signature",
+    listArchitectures: "list-architectures",
+    inspectPlist: "inspect-plist",
+    demangleSwift: "demangle-swift",
+    evidenceImport: "evidence-import",
+    evidenceExport: "evidence-export",
+    compare: "compare",
+    captureProcess: "capture-process",
+    compareProcessCaptures: "compare-process-captures",
+    listBrowserTargets: "list-browser-targets",
+    inspectWebPage: "inspect-web-page",
+    analyzeWebBundle: "analyze-web-bundle",
+    exportWebScripts: "export-web-scripts",
+    recoverJavaScriptSources: "recover-javascript-sources",
+    observeWebSession: "observe-web-session",
+    discoverWebMcpTools: "discover-webmcp-tools",
+    compareWebCaptures: "compare-web-captures",
+    captureWebScreenshot: "capture-web-screenshot",
+    compareWebScreenshots: "compare-web-screenshots",
+    captureBrowserScenario: "capture-browser-scenario",
+    listElectronTargets: "list-electron-targets",
+    inspectElectronPage: "inspect-electron-page",
+    captureElectronScenario: "capture-electron-scenario",
+    listJavaScriptRuntimeTargets: "list-javascript-runtime-targets",
+    observeJavaScriptRuntime: "observe-javascript-runtime",
+    analyzeJavaScriptApplication: "analyze-javascript-application",
+    reconcileJavaScriptRuntime: "reconcile-javascript-runtime",
+    traceApplicationFeature: "trace-application-feature",
+    traceJavaScriptSemantics: "trace-javascript-semantics",
+    compareApplicationVersions: "compare-application-versions",
+    compareSourceToBundle: "compare-source-to-bundle",
+    compareJavaScriptExportShapes: "compare-javascript-export-shapes",
+    buildReconstructionObligationLedger: "build-reconstruction-obligation-ledger",
+    evaluateReconstructionCoverage: "evaluate-reconstruction-coverage",
+    projectAndroidApplicationGraph: "project-android-application-graph",
+    projectAppleApplicationGraph: "project-apple-application-graph",
+    projectHarmonyApplicationGraph: "project-harmony-application-graph",
+});
+/** Ordered primary CLI inventory; aliases are intentionally excluded. */
+export const CLI_COMMAND_NAMES = Object.freeze(Object.values(CLI_COMMANDS));
+/** Command aliases registered on top of the primary CLI command inventory. */
+export const CLI_COMMAND_ALIASES = Object.freeze(["compare-bundles"]);
+/** Canonical MCP operations reached by CLI commands with different names. */
+export const CLI_COMMAND_TOOL_ALIASES = Object.freeze({
+    analyze: ["binary_overview"],
+    inspect: ["binary_overview"],
+    decompile: ["procedure_pseudo_code"],
+    function: ["analyze_function"],
+    instructions: ["read_function_instructions"],
+    trace: ["trace_feature"],
+    search: ["search_strings", "search_procedures"],
+    "capture-process": ["capture_process_scenario"],
+    "compare-bundles": ["compare_bundles"],
+});
+/** MCP operations without a dedicated CLI command or direct command alias. */
+export const MCP_TOOLS_WITHOUT_DEDICATED_CLI = Object.freeze([
+    "address_name",
+    "comment",
+    "current_address",
+    "current_procedure",
+    "current_document",
+    "goto_address",
+    "inline_comment",
+    "list_bookmarks",
+    "list_documents",
+    "list_names",
+    "list_procedures",
+    "list_segments",
+    "list_strings",
+    "next_address",
+    "prev_address",
+    "procedure_address",
+    "procedure_assembly",
+    "procedure_callees",
+    "procedure_callers",
+    "procedure_info",
+    "procedure_references",
+    "resolve_containing_procedure",
+    "set_address_name",
+    "set_addresses_names",
+    "set_bookmark",
+    "set_comment",
+    "set_inline_comment",
+    "unset_bookmark",
+    "get_objc_classes",
+    "get_objc_protocols",
+    "batch_decompile",
+    "get_call_graph",
+    "analyze_swift_types",
+    "find_xrefs_to_name",
+    "trace_call_path",
+    "open_binary",
+    "close_binary",
+    "binary_session",
+    "export_evidence_bundle",
+    "import_evidence_bundle",
+    "compare_artifacts",
+    "compare_functions",
+    "find_changed_behavior",
+    "build_call_path",
+    "correlate_static_and_runtime",
+    "verify_reconstruction",
+    "list_unknowns",
+    "record_unknown",
+    "update_unknown",
+    "verify_unknown_resolution",
+    "get_evidence_bundle",
+    "get_navigation_context",
+    "inspect_address_context",
+]);

package/dist/cliEvidenceCommands.js

@@ -0,0 +1,51 @@
+import { Cli, z } from "incur";
+import { compareEvidenceBundlesCommand, exportEvidenceBundleCommand, importEvidenceBundleCommand, } from "./application/EvidenceBundleCommands.js";
+import { logCliCommand } from "./cliLogging.js";
+import { CLI_COMMANDS } from "./cliCommandNames.js";
+import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
+/** Register caller-path Evidence commands. */
+export const registerEvidenceCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.evidenceImport, {
+        description: "Validate and import a bounded local Evidence bundle",
+        args: z.object({
+            path: z.string().describe("Evidence bundle JSON path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "evidence-import", async () => {
+            const imported = await importEvidenceBundleCommand(args.path);
+            return imported.ok ? imported.value : cliError(imported.error);
+        }),
+    });
+    cli.command(CLI_COMMANDS.evidenceExport, {
+        description: "Validate and atomically export canonical Evidence JSON",
+        args: z.object({
+            source: z.string().describe("Existing evidence bundle JSON path"),
+            output: z.string().describe("Canonical output JSON path"),
+        }),
+        options: z.object({
+            overwrite: z.boolean().default(false).describe("Replace output file"),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "evidence-export", async () => {
+            const exported = await exportEvidenceBundleCommand(args.source, args.output, options.overwrite);
+            return exported.ok ? exported.value : cliError(exported.error);
+        }),
+    });
+    cli.command(CLI_COMMANDS.compare, {
+        aliases: ["compare-bundles"],
+        description: "Compare two canonical Evidence bundles",
+        args: z.object({
+            left: z.string().describe("Left Evidence bundle JSON path"),
+            right: z.string().describe("Right Evidence bundle JSON path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "compare", async () => {
+            const compared = await compareEvidenceBundlesCommand({
+                leftPath: args.left,
+                rightPath: args.right,
+            });
+            return compared.ok ? compared.value : cliError(compared.error);
+        }),
+    });
+};
+const cliError = (error) => ({
+    error: "Analysis failed",
+    ...projectAnalysisError(error),
+});

package/dist/cliJavaScriptRuntimeCommands.js

@@ -0,0 +1,69 @@
+import { Cli, z } from "incur";
+import { listJavaScriptRuntimeTargets, observeJavaScriptRuntime, } from "./application/javascript/JavaScriptRuntimeObservationService.js";
+import { createJavaScriptRuntimeObservationProvider } from "./composition/javascriptRuntimeObservation.js";
+import { CLI_COMMANDS } from "./cliCommandNames.js";
+import { logCliCommand } from "./cliLogging.js";
+import { javascriptRuntimeKindSchema, listJavaScriptRuntimeTargetsInputSchema, observeJavaScriptRuntimeInputSchema, } from "./domain/javascript/javascriptRuntimeObservation.js";
+import { AnalysisInputError } from "./domain/analysisErrorCore.js";
+import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
+const observeOptionsSchema = z.object({
+    runtimeKind: javascriptRuntimeKindSchema
+        .optional()
+        .describe("Declared target role; Inspector cannot authenticate the Electron role"),
+    observationMs: z
+        .number()
+        .int()
+        .min(0)
+        .default(100)
+        .describe("Observation window in milliseconds"),
+});
+/** Register CLI equivalents of passive V8 Inspector tools. */
+export const registerJavaScriptRuntimeObservationCommands = (cli, logger) => {
+    cli.command(CLI_COMMANDS.listJavaScriptRuntimeTargets, {
+        description: "List Node/Electron V8 Inspector targets",
+        args: z.object({
+            endpoint: z.string().describe("Literal-loopback Inspector endpoint"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.listJavaScriptRuntimeTargets, async () => {
+            const context = runtimeContext();
+            const parsed = listJavaScriptRuntimeTargetsInputSchema.safeParse({
+                inspector_endpoint: args.endpoint,
+            });
+            if (!parsed.success)
+                return inputError("list_javascript_runtime_targets");
+            const result = await listJavaScriptRuntimeTargets(context.provider, parsed.data);
+            return result.ok ? result.value : cliError(result.error);
+        }),
+    });
+    cli.command(CLI_COMMANDS.observeJavaScriptRuntime, {
+        description: "Passively observe one exact Node/Electron Inspector target",
+        args: z.object({
+            endpoint: z.string().describe("Literal-loopback Inspector endpoint"),
+            targetId: z
+                .string()
+                .describe("Target from list-javascript-runtime-targets"),
+        }),
+        options: observeOptionsSchema,
+        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.observeJavaScriptRuntime, async () => {
+            const context = runtimeContext();
+            const parsed = observeJavaScriptRuntimeInputSchema.safeParse({
+                inspector_endpoint: args.endpoint,
+                target_id: args.targetId,
+                runtime_kind: options.runtimeKind,
+                observation_ms: options.observationMs,
+            });
+            if (!parsed.success)
+                return inputError("observe_javascript_runtime");
+            const result = await observeJavaScriptRuntime(context.provider, parsed.data);
+            return result.ok ? result.value : cliError(result.error);
+        }),
+    });
+};
+const runtimeContext = () => ({
+    provider: createJavaScriptRuntimeObservationProvider(),
+});
+const inputError = (operation) => cliError(new AnalysisInputError(operation));
+const cliError = (error) => ({
+    error: "JavaScript runtime observation failed",
+    ...projectAnalysisError(error),
+});

package/dist/cliJsonInput.js

@@ -0,0 +1,129 @@
+import { resolve } from "node:path";
+import { readJsonInputFile } from "./application/JsonInputFile.js";
+import { NonRegularFileReadError } from "./filesystem/RegularFile.js";
+import { AnalysisAccessDeniedError, AnalysisInputError, } from "./domain/analysisErrorCore.js";
+import { projectAnalysisError } from "./domain/analysisErrorProjection.js";
+import { safeParseJson } from "./domain/safeJson.js";
+/** Parse inline JSON or one local JSON file for a CLI workflow. */
+export const parseCliJsonInput = async (value, operation) => {
+    const inline = safeParseJson(value);
+    if (inline.ok)
+        return { ok: true, value: inline.value };
+    try {
+        const parsed = await readJsonInputFile(value, operation);
+        return parsed.ok
+            ? { ok: true, value: parsed.value }
+            : {
+                ok: false,
+                error: {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(parsed.error),
+                    input_path: value,
+                    input_reason: parsed.error._tag === "AnalysisInputError"
+                        ? "invalid-json"
+                        : "too-large",
+                },
+            };
+    }
+    catch (cause) {
+        const systemCode = accessDeniedSystemCode(cause);
+        if (systemCode !== undefined)
+            return jsonAccessDeniedError(value, operation, systemCode, cause);
+        if (["{", "["].includes(value.trimStart()[0] ?? "") &&
+            cannotBeAnExistingFile(cause) &&
+            !hasExplicitJsonFileExtension(value))
+            return { ok: false, error: inputError(operation) };
+        if (!(cause instanceof Error) ||
+            !("code" in cause) ||
+            typeof cause.code !== "string")
+            throw cause;
+        return jsonFileError(value, operation, "read-failed", cause);
+    }
+};
+const accessDeniedSystemCode = (cause) => {
+    if (!(cause instanceof Error) || !("code" in cause))
+        return undefined;
+    return cause.code === "EACCES" || cause.code === "EPERM"
+        ? cause.code
+        : undefined;
+};
+/**
+ * Resolve named string fields of CLI-supplied JSON against the operator
+ * working directory. Each entry is a key path from the document root; only
+ * fields holding nonblank strings are resolved, everything else passes through
+ * untouched so shared schemas can reject blank paths. Shared MCP contracts reject
+ * relative paths, so CLI workflows resolve operator-relative values before validation.
+ */
+export const resolveCliJsonPaths = (value, paths) => {
+    let resolved = value;
+    for (const keys of paths)
+        resolved = resolveJsonPath(resolved, keys);
+    return resolved;
+};
+const resolveJsonPath = (value, keys) => {
+    const [head, ...tail] = keys;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return value;
+    const entries = Object.entries(value).map(([key, entry]) => {
+        if (key !== head)
+            return [key, entry];
+        if (tail.length === 0)
+            return [
+                key,
+                typeof entry === "string" && entry.trim().length > 0
+                    ? resolve(entry)
+                    : entry,
+            ];
+        return [key, resolveJsonPath(entry, tail)];
+    });
+    return Object.fromEntries(entries);
+};
+const cannotBeAnExistingFile = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    (cause.code === "ENOENT" ||
+        cause.code === "ENAMETOOLONG" ||
+        cause.code === "ENOTDIR");
+const hasExplicitJsonFileExtension = (value) => value.toLowerCase().endsWith(".json");
+const inputError = (operation) => ({
+    error: "Application workflow failed",
+    ...projectAnalysisError(new AnalysisInputError(operation, undefined, [
+        { path: [], reason: "invalid_format", expected: "JSON" },
+    ])),
+});
+const jsonFileError = (path, operation, reason, cause) => ({
+    ok: false,
+    error: {
+        error: "Application workflow failed",
+        ...projectAnalysisError(new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, reason === "invalid-json"
+            ? [{ path: [], reason: "invalid_format", expected: "JSON" }]
+            : [readFailureIssue(path, cause)])),
+        ...(path === undefined ? {} : { input_path: path }),
+        input_reason: reason,
+    },
+});
+const jsonAccessDeniedError = (path, operation, systemCode, cause) => ({
+    ok: false,
+    error: {
+        error: "Application workflow failed",
+        ...projectAnalysisError(new AnalysisAccessDeniedError(operation, path, systemCode, { cause })),
+        input_path: path,
+        input_reason: "read-failed",
+    },
+});
+/** Preserve file-selection and system failures alongside the requested path. */
+const readFailureIssue = (path, cause) => {
+    const code = typeof cause === "object" &&
+        cause !== null &&
+        "code" in cause &&
+        typeof cause.code === "string"
+        ? ` (${cause.code})`
+        : "";
+    return {
+        path: [],
+        reason: "invalid_value",
+        message: cause instanceof NonRegularFileReadError && cause.code === "ENOTFILE"
+            ? `The JSON input must be a regular file${code}: ${path ?? ""}`
+            : `The JSON input file could not be read${code}: ${path ?? ""}`,
+    };
+};