feat(native): add inspection primitives, dispatch traces and approved UI observation (#500)
* fix(hopper): normalize string-backed addresses and update verification * feat(native): add inspection primitives, dispatch traces and approved UI observation * test: prioritize real artifact E2E and captured golden regressions * fix(process): queue observed output before reactive rendering actions * test: prune redundant cases and strengthen boundary assertions * fix(cli): route native value tracing through shared workflows * test: replace synthetic success with real workflows and captured data * fix(catalog): separate portable metadata from native host availability
This commit is contained in:
@@ -14,6 +14,83 @@ export const registerArtifactCommands = (
|
||||
registerInspectionCommand(cli, logger);
|
||||
registerExtractionCommand(cli, logger);
|
||||
registerInterfaceBuilderCommand(cli, logger);
|
||||
registerAssetCatalogCommand(cli, logger);
|
||||
cli.command(CLI_COMMANDS.inspectKeyedArchive, {
|
||||
description:
|
||||
"Inspect a Foundation keyed archive as an object-reference graph",
|
||||
args: z.object({
|
||||
path: z.string().describe("Foundation plist archive or Apple app bundle"),
|
||||
archive: z
|
||||
.string()
|
||||
.default(".")
|
||||
.describe("Relative archive path when the target is a bundle"),
|
||||
}),
|
||||
options: z.object({
|
||||
root: z.string().optional().describe("Named $top archive root"),
|
||||
offset: z
|
||||
.number()
|
||||
.int()
|
||||
.min(0)
|
||||
.default(0)
|
||||
.describe("First original object-table index"),
|
||||
limit: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(20000)
|
||||
.default(20000)
|
||||
.describe("Maximum object-table entries to return"),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.inspectKeyedArchive, () =>
|
||||
runProviderAnalysis(
|
||||
args.path,
|
||||
"inspect_keyed_archive",
|
||||
{
|
||||
path: args.archive,
|
||||
offset: options.offset,
|
||||
limit: options.limit,
|
||||
...(options.root === undefined ? {} : { root: options.root }),
|
||||
},
|
||||
logger,
|
||||
),
|
||||
),
|
||||
});
|
||||
};
|
||||
|
||||
const registerAssetCatalogCommand = (
|
||||
cli: CliInstance,
|
||||
logger: Logger,
|
||||
): void => {
|
||||
cli.command(CLI_COMMANDS.inspectAssetCatalog, {
|
||||
description: "Inspect compiled Apple asset catalog metadata",
|
||||
args: z.object({ path: z.string().describe("Apple .app bundle path") }),
|
||||
options: z.object({
|
||||
offset: z
|
||||
.number()
|
||||
.int()
|
||||
.min(0)
|
||||
.default(0)
|
||||
.describe("First metadata record"),
|
||||
limit: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(10_000)
|
||||
.default(1_000)
|
||||
.describe("Maximum records to return"),
|
||||
}),
|
||||
alias: {},
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.inspectAssetCatalog, () =>
|
||||
runProviderAnalysis(
|
||||
args.path,
|
||||
"inspect_asset_catalog",
|
||||
{ offset: options.offset, limit: options.limit },
|
||||
logger,
|
||||
),
|
||||
),
|
||||
});
|
||||
};
|
||||
|
||||
const registerInterfaceBuilderCommand = (
|
||||
|
||||
@@ -15,6 +15,141 @@ export const registerCoreAnalysisCommands = (
|
||||
logger: Logger,
|
||||
): void => {
|
||||
registerCoreCommands(cli, logger);
|
||||
cli.command(CLI_COMMANDS.traceNativeValues, {
|
||||
description: "Trace bounded native def-use and call dependencies",
|
||||
args: z.object({
|
||||
path: z.string().describe("Local native executable or app path"),
|
||||
procedure: z
|
||||
.string()
|
||||
.describe("Explicit native procedure symbol or address"),
|
||||
}),
|
||||
options: z.object({
|
||||
maxDepth: z
|
||||
.number()
|
||||
.int()
|
||||
.min(0)
|
||||
.max(16)
|
||||
.default(3)
|
||||
.describe("Maximum call traversal depth"),
|
||||
maxFunctions: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(64)
|
||||
.default(16)
|
||||
.describe("Maximum function decompilations"),
|
||||
maxCallSites: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(4096)
|
||||
.default(256)
|
||||
.describe("Maximum static call-site resolutions"),
|
||||
maxNodes: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(20000)
|
||||
.default(5000)
|
||||
.describe("Maximum retained graph nodes"),
|
||||
maxEdges: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(40000)
|
||||
.default(10000)
|
||||
.describe("Maximum retained graph edges"),
|
||||
offset: z
|
||||
.number()
|
||||
.int()
|
||||
.min(0)
|
||||
.default(0)
|
||||
.describe("First graph node index"),
|
||||
limit: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(5000)
|
||||
.default(1000)
|
||||
.describe("Maximum nodes on this page"),
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
alias: {
|
||||
maxDepth: "max-depth",
|
||||
maxFunctions: "max-functions",
|
||||
maxCallSites: "max-call-sites",
|
||||
maxNodes: "max-nodes",
|
||||
maxEdges: "max-edges",
|
||||
},
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.traceNativeValues, () =>
|
||||
runDirectAnalysis(
|
||||
args.path,
|
||||
"trace_native_values",
|
||||
{
|
||||
procedure: args.procedure,
|
||||
max_depth: options.maxDepth,
|
||||
max_functions: options.maxFunctions,
|
||||
max_call_sites: options.maxCallSites,
|
||||
max_nodes: options.maxNodes,
|
||||
max_edges: options.maxEdges,
|
||||
offset: options.offset,
|
||||
limit: options.limit,
|
||||
},
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
),
|
||||
),
|
||||
});
|
||||
cli.command(CLI_COMMANDS.inspectNativeDataType, {
|
||||
description: "Inspect one recovered database type or typed data object",
|
||||
args: z.object({
|
||||
path: z.string().describe("Local native executable or app path"),
|
||||
}),
|
||||
options: z.object({
|
||||
type: z.string().optional().describe("Exact database type category path"),
|
||||
address: z.string().describe("Exact native address").optional(),
|
||||
provider: providerSelectionOption,
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.inspectNativeDataType, () =>
|
||||
runDirectAnalysis(
|
||||
args.path,
|
||||
"inspect_native_data_type",
|
||||
{
|
||||
...(options.type === undefined ? {} : { type: options.type }),
|
||||
...(options.address === undefined
|
||||
? {}
|
||||
: { address: options.address }),
|
||||
},
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
),
|
||||
),
|
||||
});
|
||||
for (const [command, operation] of [
|
||||
[CLI_COMMANDS.inspectNativeInstruction, "inspect_native_instruction"],
|
||||
[CLI_COMMANDS.resolveNativeCallTargets, "resolve_native_call_targets"],
|
||||
] as const) {
|
||||
cli.command(command, {
|
||||
description:
|
||||
operation === "inspect_native_instruction"
|
||||
? "Inspect one native instruction with decoded operand facts"
|
||||
: "Resolve one static native call site",
|
||||
args: z.object({
|
||||
path: z.string().describe("Local native executable or app path"),
|
||||
address: z.string().describe("Exact native address"),
|
||||
}),
|
||||
options: z.object({ provider: providerSelectionOption }),
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, command, () =>
|
||||
runDirectAnalysis(
|
||||
args.path,
|
||||
operation,
|
||||
{ address: args.address },
|
||||
directAnalysisOptions(logger, undefined, options.provider),
|
||||
),
|
||||
),
|
||||
});
|
||||
}
|
||||
registerFunctionCommand(cli, logger);
|
||||
registerNativeApiCommand(cli, logger);
|
||||
registerInstructionsCommand(cli, logger);
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import { z } from "incur";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
|
||||
import {
|
||||
runCapabilityStatus,
|
||||
@@ -21,6 +22,95 @@ export const registerUtilityCommands = (
|
||||
): void => {
|
||||
registerCapabilityCommands(cli, logger);
|
||||
registerNativeCommands(cli, logger);
|
||||
for (const [command, operation] of [
|
||||
[CLI_COMMANDS.observeNativeUi, "observe_native_ui"],
|
||||
[CLI_COMMANDS.captureNativeUiScenario, "capture_native_ui_scenario"],
|
||||
] as const) {
|
||||
cli.command(command, {
|
||||
description:
|
||||
"Observe or run an approved scenario in one exact native application window",
|
||||
args: z.object({
|
||||
path: z.string().describe("Local native executable or app path"),
|
||||
}),
|
||||
options: z.object({
|
||||
pid: z
|
||||
.number()
|
||||
.int()
|
||||
.positive()
|
||||
.describe("Approved existing application PID"),
|
||||
windowId: z
|
||||
.number()
|
||||
.int()
|
||||
.positive()
|
||||
.describe("Exact selected application window ID"),
|
||||
observationApproved: z
|
||||
.boolean()
|
||||
.default(false)
|
||||
.describe("Approve passive observation of this PID/window"),
|
||||
actionsApproved: z
|
||||
.boolean()
|
||||
.default(false)
|
||||
.describe("Independently approve scenario actions"),
|
||||
restore: z
|
||||
.enum(["leave-as-is"])
|
||||
.optional()
|
||||
.describe("Explicit choice to leave application state as-is"),
|
||||
steps: z
|
||||
.string()
|
||||
.optional()
|
||||
.describe("JSON array of approved declarative AX actions or waits"),
|
||||
screenshot: z
|
||||
.boolean()
|
||||
.default(true)
|
||||
.describe("Capture only the selected window"),
|
||||
accessibility: z
|
||||
.boolean()
|
||||
.default(true)
|
||||
.describe("Read the selected window accessibility tree"),
|
||||
maxNodes: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(2000)
|
||||
.default(500)
|
||||
.describe("Maximum accessibility nodes per capture"),
|
||||
}),
|
||||
alias: {
|
||||
windowId: "window-id",
|
||||
observationApproved: "observation-approved",
|
||||
actionsApproved: "actions-approved",
|
||||
maxNodes: "max-nodes",
|
||||
},
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, command, () =>
|
||||
runProviderAnalysis(
|
||||
args.path,
|
||||
operation,
|
||||
{
|
||||
pid: options.pid,
|
||||
window_id: options.windowId,
|
||||
observation_approved: options.observationApproved,
|
||||
screenshot: options.screenshot,
|
||||
accessibility: options.accessibility,
|
||||
max_nodes: options.maxNodes,
|
||||
...(operation === "capture_native_ui_scenario"
|
||||
? {
|
||||
actions_approved: options.actionsApproved,
|
||||
...(options.restore === undefined
|
||||
? {}
|
||||
: { restore: options.restore }),
|
||||
steps:
|
||||
options.steps === undefined
|
||||
? []
|
||||
: jsonValueSchema.parse(JSON.parse(options.steps)),
|
||||
}
|
||||
: {}),
|
||||
},
|
||||
logger,
|
||||
),
|
||||
),
|
||||
});
|
||||
}
|
||||
registerReferenceSourceCommand(cli, logger);
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user