rea-agents 6.4.0 → 6.5.0

package/dist/apktool/ApktoolDecodeOutput.js

@@ -1,59 +1,142 @@
+import { DOMParser, } from "@xmldom/xmldom";
+import { isMap, isScalar, parseDocument, } from "yaml";
+const metaInfoTag = {
+    tag: "tag:yaml.org,2002:brut.androlib.meta.MetaInfo",
+    collection: "map",
+    resolve: (map) => map,
+};
 /**
- * Parsers for the decoded workspace `apktool d --no-src` produces.
- *
- * Apktool's apktool.yml is a small YAML document; the facts REA projects
- * are flat enough that line-oriented extraction stays honest without a
- * YAML dependency, and unrecognized content is ignored rather than guessed.
- */
-/**
- * Project version and SDK facts from apktool.yml. Values keep apktool's
- * own spelling (version codes can print as `45` or `45.1`).
+ * Read values from Apktool's tagged metadata document. YAML's core schema
+ * distinguishes null from quoted strings; numeric values use their source
+ * range so version codes retain the spelling Apktool emitted.
  */
 export const parseApktoolYml = (yml) => {
-    const metadata = {
-        versionName: null,
-        versionCode: null,
-        minSdkVersion: null,
-        targetSdkVersion: null,
+    const document = parseDocument(yml, {
+        schema: "core",
+        customTags: [metaInfoTag],
+        strict: true,
+        uniqueKeys: true,
+    });
+    if (document.errors.length > 0)
+        throw new TypeError(`apktool.yml is not valid Apktool metadata: ${document.errors[0]?.message ?? "YAML parse error"}`);
+    if (!isMap(document.contents))
+        throw new TypeError("apktool.yml root must be an Apktool metadata mapping");
+    return {
+        versionName: yamlScalar(document, ["versionInfo", "versionName"], yml),
+        versionCode: yamlScalar(document, ["versionInfo", "versionCode"], yml),
+        minSdkVersion: yamlScalar(document, ["sdkInfo", "minSdkVersion"], yml),
+        targetSdkVersion: yamlScalar(document, ["sdkInfo", "targetSdkVersion"], yml),
     };
-    for (const line of yml.split(/\r?\n/u)) {
-        const versionName = /^\s*versionName:\s*(?:'([^']*)'|(.*))$/u.exec(line);
-        if (versionName !== null && metadata.versionName === null)
-            metadata.versionName = (versionName[1] ?? versionName[2] ?? "").trim();
-        const versionCode = /^\s*versionCode:\s*(?:'([^']*)'|(.*))$/u.exec(line);
-        if (versionCode !== null && metadata.versionCode === null)
-            metadata.versionCode = (versionCode[1] ?? versionCode[2] ?? "").trim();
-        const minSdk = /minSdkVersion:\s*'?([0-9]+)'?/u.exec(line);
-        if (minSdk !== null && metadata.minSdkVersion === null)
-            metadata.minSdkVersion = minSdk[1];
-        const targetSdk = /targetSdkVersion:\s*'?([0-9]+)'?/u.exec(line);
-        if (targetSdk !== null && metadata.targetSdkVersion === null)
-            metadata.targetSdkVersion = targetSdk[1];
-    }
-    return metadata;
 };
-/** Read the package attribute from decoded AndroidManifest.xml text. */
+/** Read the package attribute from the decoded Android manifest root. */
 export const parseManifestPackage = (manifest) => {
-    const match = /<manifest[^>]*\spackage="([^"]+)"/u.exec(manifest);
-    return match === null ? null : match[1];
+    const document = parseXml(manifest, "AndroidManifest.xml");
+    const root = document.documentElement;
+    if (root === null || root.nodeName !== "manifest")
+        throw new TypeError("AndroidManifest.xml root must be <manifest>");
+    return root.getAttribute("package") || null;
 };
 /**
- * Project `<string name="...">value</string>` entries from one decoded
- * strings.xml. Values are preserved exactly as apktool printed them —
- * escaped entities stay escaped — and entries containing nested markup
- * are counted as unparsed rather than flattened.
+ * Project direct `<string>` children from decoded resources XML. DOM parsing
+ * identifies elements and attributes; text values are sliced from the input
+ * at parser-reported locations so entity spelling and whitespace are kept.
+ * Markup-bearing string values are omitted and counted as partial evidence.
  */
 export const parseDecodedStrings = (stringsXml) => {
+    let document;
+    try {
+        document = parseXml(stringsXml, "strings.xml");
+    }
+    catch {
+        return { entries: [], unparsedCount: 1 };
+    }
+    const root = document.documentElement;
+    if (root === null || root.nodeName !== "resources")
+        return { entries: [], unparsedCount: 1 };
     const entries = [];
     let unparsedCount = 0;
-    const pattern = /<string\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/string>/gu;
-    for (let match = pattern.exec(stringsXml); match !== null; match = pattern.exec(stringsXml)) {
-        const value = match[2];
-        if (value.includes("<")) {
+    const offsets = sourceLineOffsets(stringsXml);
+    for (const child of childNodes(root)) {
+        if (child.nodeType !== 1)
+            continue;
+        const element = child;
+        if (element.nodeName !== "string")
+            continue;
+        const name = element.getAttribute("name");
+        if (name === null || name.length === 0) {
+            unparsedCount += 1;
+            continue;
+        }
+        const content = childNodes(element);
+        if (content.some((node) => node.nodeType !== 3 && node.nodeType !== 8)) {
             unparsedCount += 1;
             continue;
         }
-        entries.push({ name: match[1], value: value.trim() });
+        if (content.every((node) => node.nodeType === 8)) {
+            entries.push({ name, value: "" });
+            continue;
+        }
+        const value = content
+            .filter((node) => node.nodeType === 3)
+            .map((node) => {
+            const start = sourceOffset(node, offsets);
+            if (start === undefined)
+                return null;
+            // A literal '<' cannot appear in well-formed XML text. Ending here
+            // also excludes comments after the document element from this value.
+            const end = stringsXml.indexOf("<", start);
+            if (end < start)
+                return null;
+            return stringsXml.slice(start, end);
+        });
+        if (value.some((part) => part === null)) {
+            unparsedCount += 1;
+            continue;
+        }
+        entries.push({ name, value: value.join("") });
     }
     return { entries, unparsedCount };
 };
+const yamlScalar = (document, path, source) => {
+    const node = document.getIn(path, true);
+    if (!isScalar(node) || node.value === null)
+        return null;
+    if (typeof node.value === "string")
+        return node.value;
+    const range = node.range;
+    return range === null || range === undefined
+        ? String(node.value)
+        : source.slice(range[0], range[1]);
+};
+const parseXml = (xml, label) => {
+    const errors = [];
+    const document = new DOMParser({
+        normalizeLineEndings: (source) => source,
+        onError: (_level, message) => errors.push(message),
+    }).parseFromString(xml, "application/xml");
+    if (errors.length > 0 || document.documentElement === null)
+        throw new TypeError(`${label} is not well-formed XML${errors[0] === undefined ? "" : `: ${errors[0]}`}`);
+    return document;
+};
+const childNodes = (node) => {
+    const children = [];
+    for (let child = node.firstChild; child !== null; child = child.nextSibling)
+        children.push(child);
+    return children;
+};
+const sourceLineOffsets = (source) => {
+    const offsets = [0];
+    for (const match of source.matchAll(/\r\n?|\n/gu)) {
+        const index = match.index;
+        offsets.push(index + match[0].length);
+    }
+    return offsets;
+};
+const sourceOffset = (node, lineOffsets) => {
+    const line = node.lineNumber;
+    const column = node.columnNumber;
+    if (line === undefined || column === undefined)
+        return undefined;
+    const lineStart = lineOffsets[line - 1];
+    return lineStart === undefined ? undefined : lineStart + column - 1;
+};

package/dist/apktool/ApktoolProvider.js

@@ -1,11 +1,13 @@
 import { createHash, randomUUID } from "node:crypto";
-import { createWriteStream, constants as fsConstants } from "node:fs";
+import { createWriteStream } from "node:fs";
 import { access, chmod, mkdir, mkdtemp, opendir, open, rm, stat, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
+import { providerConfigurationRefusal } from "../domain/providerConfigurationRefusal.js";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { androidLocaleQualifierSchema, } from "../domain/apktool/apktoolResourceAnalysis.js";
 import { AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisInputError, AnalysisProtocolError, AnalysisResourceConstraintError, AnalysisTimeoutError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
 import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 import { err, ok } from "../domain/result.js";
@@ -13,7 +15,8 @@ import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { openRegularFile, sameRegularFileState, } from "../filesystem/RegularFile.js";
 import { OwnedCommandFailure, runOwnedCommand, } from "../process/OwnedCommand.js";
 import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
-import { ApktoolConfigurationFailure, apktoolConfigurationAvailability, inspectApktoolClient, resolveApktoolCommand, } from "./ApktoolConfiguration.js";
+import { WindowsBatchCommandError } from "../process/WindowsBatchCommand.js";
+import { APKTOOL_COMMAND_ENV, ApktoolConfigurationFailure, apktoolConfigurationAvailability, apktoolInvocation, inspectApktoolClient, resolveApktoolCommand, } from "./ApktoolConfiguration.js";
 import { parseApktoolYml, parseDecodedStrings, parseManifestPackage, } from "./ApktoolDecodeOutput.js";
 /** Stable identity for the Apktool resource-decoding provider. */
 export const APKTOOL_PROVIDER_IDENTITY = {
@@ -55,28 +58,44 @@ const readBoundedText = async (path, budget, operation, signal) => {
         throwIfCancelled(operation, signal);
         const truncated = length > budget;
         // A prefix may end within a UTF-8 character; omit those trailing bytes.
-        const decoder = new TextDecoder("utf-8");
-        return {
-            text: decoder.decode(bytes.subarray(0, Math.min(length, budget)), {
-                stream: truncated,
-            }),
-            truncated,
-        };
+        try {
+            const decoder = new TextDecoder("utf-8", { fatal: true });
+            return {
+                text: decoder.decode(bytes.subarray(0, Math.min(length, budget)), {
+                    stream: truncated,
+                }),
+                truncated,
+            };
+        }
+        catch (cause) {
+            throw new AnalysisProtocolError(`apktool produced invalid UTF-8 in ${path}`, { cause });
+        }
     }
     finally {
         await file.close();
     }
 };
 const localeQualifier = (locale) => locale.replace(/^([a-z]{2,3})-([A-Z]{2}|[0-9]{3})$/u, "$1-r$2");
-const runApktool = async (operation, command, arguments_, limits, signal, environment, onCleanupOwner) => {
+const runApktool = async (operation, selection, arguments_, limits, signal, environment, onCleanupOwner) => {
     if (signal?.aborted === true)
         return err(new AnalysisCancelledError(operation));
+    let invocation;
+    try {
+        invocation = apktoolInvocation(selection, arguments_, environment);
+    }
+    catch (cause) {
+        if (!(cause instanceof WindowsBatchCommandError))
+            throw cause;
+        const reason = `The apktool batch launcher cannot receive REA's decode paths through cmd.exe: ${cause.message}`;
+        return err(new AnalysisCapabilityUnavailableError(APKTOOL_PROVIDER_IDENTITY.id, operation, reason, { cause, userMessage: reason }));
+    }
     try {
         const output = await runOwnedCommand({
-            command,
-            arguments: arguments_,
+            command: invocation.command,
+            arguments: invocation.arguments,
+            windowsVerbatimArguments: invocation.windowsVerbatimArguments,
             runId: randomUUID(),
-            hostEnvironment: { ...process.env, ...environment },
+            hostEnvironment: environment,
         }, {
             timeoutMs: limits.timeoutMs,
             diagnosticBytes: limits.maxOutputBytes,
@@ -124,7 +143,7 @@ const runApktool = async (operation, command, arguments_, limits, signal, enviro
                 ...(cleanup === undefined ? {} : { cleanup }),
                 ...(capturedOutput === undefined ? {} : { capturedOutput }),
             }));
-        return err(new AnalysisUnsupportedTargetError(operation, command, output?.stderr.text.trim().slice(0, STDERR_EXCERPT_BYTES) ||
+        return err(new AnalysisUnsupportedTargetError(operation, selection.command, output?.stderr.text.trim().slice(0, STDERR_EXCERPT_BYTES) ||
             `apktool exited with code ${String(output?.exitCode ?? "unknown")} for ${operation}`, {
             cause,
             ...(cleanup === undefined ? {} : { cleanup }),
@@ -155,6 +174,7 @@ const countDecodedFiles = async (root, signal, operation) => {
                 if (directory === join(root, "res")) {
                     const match = /^values-(.+)$/u.exec(entry.name);
                     if (match !== null &&
+                        androidLocaleQualifierSchema.safeParse(match[1]).success &&
                         (await access(join(path, "strings.xml")).then(() => true, () => false)))
                         locales.push(match[1]);
                 }
@@ -173,7 +193,7 @@ const countDecodedFiles = async (root, signal, operation) => {
  * (`--no-src`) because Java-source recovery belongs to the JADX family.
  */
 export class ApktoolProvider {
-    environment;
+    selectedEnvironment;
     workspaces = new Set();
     removeWorkspace;
     #pendingCommandOwners = new Map();
@@ -182,13 +202,25 @@ export class ApktoolProvider {
     #closing = false;
     #closePromise;
     constructor(options = {}) {
-        this.environment = snapshotEnvironment(options.environment ?? process.env);
+        this.selectedEnvironment =
+            options.environment === undefined
+                ? undefined
+                : snapshotEnvironment(options.environment);
         this.removeWorkspace =
             options.removeWorkspace ??
                 ((path) => rm(path, { recursive: true, force: true }));
     }
-    selection() {
-        return resolveApktoolCommand(this.environment);
+    operationEnvironment() {
+        const ambient = snapshotEnvironment(process.env);
+        if (this.selectedEnvironment === undefined)
+            return ambient;
+        // Child inheritance is sampled per operation. An explicit map keeps its
+        // launcher choice authoritative, including an omitted command selecting PATH.
+        return snapshotEnvironment({
+            ...ambient,
+            ...this.selectedEnvironment,
+            [APKTOOL_COMMAND_ENV]: this.selectedEnvironment[APKTOOL_COMMAND_ENV],
+        });
     }
     /** Probe the selected apktool launcher; decodes nothing. */
     inspectAvailability(signal) {
@@ -200,9 +232,10 @@ export class ApktoolProvider {
         return this.#track(this.#inspectAvailability(operationSignal));
     }
     async #inspectAvailability(signal) {
-        const selection = this.selection();
+        const environment = this.operationEnvironment();
         try {
-            await inspectApktoolClient(selection, signal, this.environment);
+            const selection = await resolveApktoolCommand(environment, process.platform, signal);
+            await inspectApktoolClient(selection, signal, environment);
             throwIfCancelled("inspect_apktool_client", signal);
             return {
                 status: "available",
@@ -241,18 +274,20 @@ export class ApktoolProvider {
     async #execute(request, signal) {
         if (signal?.aborted === true)
             return err(new AnalysisCancelledError(request.operation));
-        const selection = this.selection();
+        const environment = this.operationEnvironment();
+        let selection;
         let identity;
         try {
-            identity = await inspectApktoolClient(selection, signal, this.environment);
+            selection = await resolveApktoolCommand(environment, process.platform, signal);
+            identity = await inspectApktoolClient(selection, signal, environment);
         }
         catch (cause) {
-            if (cause instanceof AnalysisCancelledError)
+            if (cause instanceof AnalysisCancelledError ||
+                cause instanceof AnalysisTimeoutError)
                 return err(cause);
-            if (cause instanceof ApktoolConfigurationFailure)
-                return err(new AnalysisCapabilityUnavailableError(APKTOOL_PROVIDER_IDENTITY.id, request.operation, typeof cause.diagnostics.remediation === "string"
-                    ? `${cause.message} ${cause.diagnostics.remediation}`
-                    : cause.message, { cause }));
+            if (cause instanceof ApktoolConfigurationFailure) {
+                return err(providerConfigurationRefusal(APKTOOL_PROVIDER_IDENTITY.id, request.operation, cause));
+            }
             return err(new AnalysisProtocolError(`apktool version probe failed for ${request.operation}`, { cause }));
         }
         if (signal.aborted)
@@ -268,7 +303,7 @@ export class ApktoolProvider {
         };
         if (request.operation === "inspect_apktool_client")
             return ok(createAnalysisExecution({ client }, provider));
-        return this.decodeResources(request.operation, selection, client, provider, request.input, signal);
+        return this.decodeResources(request.operation, selection, environment, client, provider, request.input, signal);
     }
     #track(operation) {
         const settled = operation.then(() => undefined, () => undefined);
@@ -304,7 +339,7 @@ export class ApktoolProvider {
         if (failures.length > 0)
             throw new AggregateError(failures, "Apktool workspace cleanup failed");
     }
-    async decodeResources(operation, selection, client, provider, input, signal) {
+    async decodeResources(operation, selection, environment, client, provider, input, signal) {
         const root = await mkdtemp(join(tmpdir(), "rea-apktool-"));
         this.workspaces.add(root);
         const workspace = join(root, "decoded");
@@ -376,7 +411,7 @@ export class ApktoolProvider {
             const snapshotInfo = await stat(snapshot);
             await mkdir(workspace);
             await mkdir(framework);
-            const decoded = await runApktool(operation, selection.command, [
+            const decoded = await runApktool(operation, selection, [
                 "d",
                 "--no-src",
                 "-f",
@@ -388,7 +423,7 @@ export class ApktoolProvider {
             ], {
                 timeoutMs: DECODE_TIMEOUT_MS,
                 maxOutputBytes: DECODE_MAX_OUTPUT_BYTES,
-            }, signal, this.environment, (owner) => this.#pendingCommandOwners.set(owner, root));
+            }, signal, environment, (owner) => this.#pendingCommandOwners.set(owner, root));
             if (!decoded.ok) {
                 await removeWorkspace();
                 return err(failureWithCleanup(decoded.error));
@@ -401,7 +436,9 @@ export class ApktoolProvider {
             const metadata = parseApktoolYml(yml.text);
             const manifestRead = await readBoundedText(join(workspace, "AndroidManifest.xml"), MANIFEST_MAX_BYTES, operation, signal);
             const manifest = manifestRead.text;
-            const packageName = manifest === null ? null : parseManifestPackage(manifest);
+            const packageName = manifest === null || manifestRead.truncated
+                ? null
+                : parseManifestPackage(manifest);
             const stringsDirectory = input.locale === undefined
                 ? "values"
                 : `values-${localeQualifier(input.locale)}`;
@@ -457,7 +494,7 @@ export class ApktoolProvider {
                         : []),
                     ...(parsedStrings.unparsedCount > 0
                         ? [
-                            `${String(parsedStrings.unparsedCount)} string entries with nested markup were not projected`,
+                            `String entries omitted due to malformed XML or unsupported markup: ${String(parsedStrings.unparsedCount)}`,
                         ]
                         : []),
                     ...(parsedStrings.entries.length > MAX_STRINGS

package/dist/application/AnalysisContextQueries.js

@@ -1,5 +1,4 @@
 import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
-import {} from "../domain/analysisErrorBase.js";
 import { analysisBookmarkSchema } from "../domain/hopperValues.js";
 import { resolveAnalysisDocument } from "./AnalysisDocument.js";
 import { err, ok } from "../domain/result.js";
@@ -15,17 +14,15 @@ export const getNavigationContext = async (analysis, input, signal) => {
     if (typeof document !== "string" && !document.ok)
         return document;
     const documentName = typeof document === "string" ? document : document.value.result;
-    const documentArgs = typeof documentName === "string" ? parameters(documentName) : {};
+    if (typeof documentName !== "string")
+        return err(new AnalysisOutputError("current_document", "expected a document identity string"));
+    const documentArgs = parameters(documentName);
     const address = await analysis.execute("current_address", documentArgs, executionOptions(signal));
     if (!address.ok)
         return address;
     if (typeof address.value.result !== "string")
-        return ok({
-            document: documentName,
-            address: address.value.result,
-            procedure: null,
-        });
-    const procedure = await analysis.execute("resolve_containing_procedure", parameters(typeof documentName === "string" ? documentName : undefined, address.value.result), executionOptions(signal));
+        return err(new AnalysisOutputError("current_address", "expected an address string"));
+    const procedure = await analysis.execute("resolve_containing_procedure", parameters(documentName, address.value.result), executionOptions(signal));
     if (!procedure.ok) {
         if (!isMissingCurrentProcedure(procedure.error))
             return procedure;

package/dist/application/AnalysisProvider.js

@@ -1,21 +1,25 @@
 import { jsonValueSchema } from "../domain/jsonValue.js";
-/**
- * Build a validated atomic provider observation at an adapter boundary.
- *
- * Pass `rawResult` only for a provider representation distinct from
- * `result`. Omitting it records `null` rather than a second complete copy of
- * the normalized result in every Evidence record and tool response.
- */
-export const createAnalysisExecution = (result, provider, options = {}) => ({
-    result: jsonValueSchema.parse(result),
-    rawResult: options.rawResult === undefined
-        ? null
-        : jsonValueSchema.parse(options.rawResult),
-    provider,
-    ...(options.analysisProfile === undefined
-        ? {}
-        : { analysisProfile: structuredClone(options.analysisProfile) }),
-    limitations: [...(options.limitations ?? [])],
-    locations: [...(options.locations ?? [])],
-    subject: options.subject ?? null,
-});
+import { relationshipCoverageSchema, } from "../domain/relationshipCoverage.js";
+export function createAnalysisExecution(result, provider, options = {}) {
+    return {
+        result: jsonValueSchema.parse(result),
+        rawResult: options.rawResult === undefined
+            ? null
+            : jsonValueSchema.parse(options.rawResult),
+        provider,
+        ...(options.analysisProfile === undefined
+            ? {}
+            : { analysisProfile: structuredClone(options.analysisProfile) }),
+        limitations: [...(options.limitations ?? [])],
+        ...(options.relationshipCoverage === undefined
+            ? {}
+            : {
+                relationshipCoverage: relationshipCoverageSchema.parse(options.relationshipCoverage),
+            }),
+        ...(options.referencesTruncated === undefined
+            ? {}
+            : { referencesTruncated: options.referencesTruncated }),
+        locations: [...(options.locations ?? [])],
+        subject: options.subject ?? null,
+    };
+}

package/dist/application/AppBundleExecutable.js

@@ -7,6 +7,7 @@ import { BinaryTargetError } from "../domain/configurationErrors.js";
 import { isPathWithinRoot } from "../domain/localPath.js";
 import { omitPrototypeKeys, parseXmlPropertyList, } from "../domain/propertyListKeys.js";
 import { decodeXmlPlistText } from "../domain/propertyListXmlText.js";
+import { hasBinaryPlistSignature } from "../domain/apple/appleArchiveFormat.js";
 import { err, ok } from "../domain/result.js";
 /** Decoded representation bound for one binary Info.plist. */
 const BINARY_PLIST_DECODE_BYTES = 16 * 1024 * 1024;
@@ -131,11 +132,10 @@ const resolveLayoutExecutable = async (bundle, layout, fileSystem) => {
     }
     let name;
     try {
-        name =
-            plist.subarray(0, 6).toString("ascii") === "bplist"
-                ? await (fileSystem.decodeBinaryPlist?.(plistPath) ??
-                    parseBinaryPlistExecutable(plist))
-                : parseXmlPlistExecutable(decodeXmlPlistText(plist));
+        name = hasBinaryPlistSignature(plist)
+            ? await (fileSystem.decodeBinaryPlist?.(plistPath) ??
+                parseBinaryPlistExecutable(plist))
+            : parseXmlPlistExecutable(decodeXmlPlistText(plist));
     }
     catch (cause) {
         return err(new BinaryTargetError(plistPath, isPermissionDenied(cause)