rea-agents 3.2.0 → 4.0.0

package/dist/application/UpdateMaintenance.js

@@ -0,0 +1,108 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
+import { readClientRegistrationStatuses } from "./ClientRegistrationStatus.js";
+import { parseClientConfiguration } from "./ClientConfigurationDocument.js";
+import { supportedClients } from "./SupportedClients.js";
+const setupPlanSchema = z.object({
+    status: z.literal("planned"),
+    plannedActions: z.array(z.object({
+        id: z.string(),
+        kind: z.enum(["configure_client", "install_skill"]),
+        label: z.string(),
+        target: z.string(),
+        detail: z.string(),
+        external: z.literal(false),
+        operation: z.enum(["create", "update", "install"]),
+        backupPath: z.string().optional(),
+        commands: z.array(z.string()).optional(),
+    })),
+});
+/** Discover owned registrations and an existing REA skill without writes. */
+export const existingMaintenanceScope = async (home, entryPoint) => {
+    const registrations = await readClientRegistrationStatuses(home, entryPoint);
+    const supported = supportedClients(home);
+    const clients = [];
+    for (const registration of registrations) {
+        if ((registration.state !== "aligned" && registration.state !== "stale") ||
+            !isOwnedClientRegistrationCommand(registration.command, entryPoint))
+            continue;
+        const client = supported.find(({ name }) => name === registration.client);
+        if (client === undefined)
+            continue;
+        const { servers } = parseClientConfiguration(await readFile(client.configPath, "utf8"), client.format);
+        const enabled = z
+            .object({
+            enabled: z.boolean().optional(),
+            disabled: z.boolean().optional(),
+        })
+            .parse(servers[PRODUCT_IDENTITY.mcpServerKey]);
+        if (enabled.enabled !== false && enabled.disabled !== true)
+            clients.push(client.name);
+    }
+    let skill = false;
+    try {
+        const content = await readFile(join(home, ".agents", "skills", PRODUCT_IDENTITY.skillName, "SKILL.md"), "utf8");
+        skill =
+            content.startsWith(`---\nname: ${PRODUCT_IDENTITY.skillName}\n`) ||
+                content.startsWith(`---\r\nname: ${PRODUCT_IDENTITY.skillName}\r\n`);
+    }
+    catch (cause) {
+        if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
+            throw cause;
+    }
+    return { clients, skill };
+};
+/** Ask the verified new executable to plan only existing REA integrations. */
+export const planIntegrationMaintenance = async (home, entryPoint, execute) => {
+    try {
+        const scope = await existingMaintenanceScope(home, entryPoint);
+        if (scope.clients.length === 0 && !scope.skill)
+            return { status: "current", plannedActions: [] };
+        const command = [
+            process.execPath,
+            entryPoint,
+            "setup",
+            ...scope.clients.flatMap((client) => ["--client", client]),
+            `--skill=${String(scope.skill)}`,
+        ];
+        const execution = await execute([...command, "--dry-run", "--json"]);
+        if (!execution.ok)
+            return { status: "unavailable", remediation: execution.error };
+        const plan = setupPlanSchema.safeParse(JSON.parse(execution.value));
+        if (!plan.success)
+            return {
+                status: "unavailable",
+                remediation: `The updated setup executable returned an invalid maintenance plan: ${plan.error.message}`,
+            };
+        if (plan.data.plannedActions.length === 0)
+            return { status: "current", plannedActions: [] };
+        const allowedIds = new Set([
+            ...scope.clients.map((client) => `configure_client:${client}`),
+            ...(scope.skill ? ["install_skill"] : []),
+        ]);
+        if (plan.data.plannedActions.some(({ id }) => !allowedIds.has(id)))
+            return {
+                status: "unavailable",
+                remediation: "The updated setup plan included an integration outside the existing REA maintenance scope.",
+            };
+        return {
+            status: "planned",
+            scope,
+            command,
+            plannedActions: plan.data.plannedActions.map(({ backupPath, commands, ...action }) => ({
+                ...action,
+                ...(backupPath === undefined ? {} : { backupPath }),
+                ...(commands === undefined ? {} : { commands }),
+            })),
+        };
+    }
+    catch (cause) {
+        return {
+            status: "unavailable",
+            remediation: cause instanceof Error ? cause.message : String(cause),
+        };
+    }
+};

package/dist/application/UpdateRuntime.js

@@ -0,0 +1,126 @@
+import { realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import spawn from "cross-spawn";
+import { z } from "zod";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { err, ok } from "../domain/result.js";
+import { updateInstallCommand, } from "./Update.js";
+import { planIntegrationMaintenance } from "./UpdateMaintenance.js";
+/** Run an updater subprocess with complete diagnostics and isolated machine output. */
+export const runUpdateCommand = (command, output = "structured") => new Promise((resolveResult) => {
+    const [executable, ...args] = command;
+    if (executable === undefined) {
+        resolveResult(err("No executable supplied."));
+        return;
+    }
+    const environment = { ...process.env };
+    // A fresh installed entry point must not inherit npx's invocation identity.
+    delete environment.npm_command;
+    const child = spawn(executable, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: environment,
+        windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+        stdout += chunk;
+        if (output === "human")
+            process.stderr.write(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk;
+        if (output === "human")
+            process.stderr.write(chunk);
+    });
+    child.once("error", (cause) => resolveResult(err(cause.message)));
+    child.once("close", (code, signal) => resolveResult(code === 0
+        ? ok(stdout.trim())
+        : err(stderr.trim() ||
+            stdout.trim() ||
+            (signal === null
+                ? `Process exited with code ${String(code)}.`
+                : `Process terminated by ${signal}.`))));
+});
+const requireCommandOutput = async (command) => {
+    const result = await runUpdateCommand(command);
+    if (!result.ok)
+        throw new Error(result.error);
+    return result.value;
+};
+/** Resolve the global prefix only when it owns the running package. */
+export const detectNpmInstallation = async (packageRoot, host) => {
+    let canonicalPackageRoot;
+    try {
+        canonicalPackageRoot = await host.canonicalPath(packageRoot);
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const npmRoot = await host.globalRoot();
+        const globalPackageRoot = await host.canonicalPath(resolve(npmRoot, PRODUCT_IDENTITY.packageName));
+        if (canonicalPackageRoot === globalPackageRoot) {
+            const prefix = await host.globalPrefix();
+            return prefix.length === 0
+                ? undefined
+                : { prefix, packageRoot: canonicalPackageRoot };
+        }
+    }
+    catch {
+        // The curl installer uses a Unix prefix that may differ from npm's current default.
+    }
+    const nodeModules = dirname(canonicalPackageRoot);
+    const library = dirname(nodeModules);
+    if (basename(canonicalPackageRoot) !== PRODUCT_IDENTITY.packageName ||
+        basename(nodeModules) !== "node_modules" ||
+        basename(library) !== "lib")
+        return undefined;
+    return { prefix: dirname(library), packageRoot: canonicalPackageRoot };
+};
+/** Create npm, registry, verification, and read-only maintenance effects. */
+export const systemUpdateHost = (packageRoot = fileURLToPath(new URL("../..", import.meta.url)), home = homedir()) => ({
+    installation: () => detectNpmInstallation(packageRoot, {
+        canonicalPath: realpath,
+        globalRoot: () => requireCommandOutput(["npm", "root", "--global"]),
+        globalPrefix: () => requireCommandOutput(["npm", "prefix", "--global"]),
+    }),
+    latestVersion: async (installation) => {
+        const response = await runUpdateCommand([
+            "npm",
+            "view",
+            "--global",
+            ...(installation === undefined ? [] : ["--prefix", installation.prefix]),
+            PRODUCT_IDENTITY.packageName,
+            "dist-tags.latest",
+            "--json",
+            "--fetch-retries=0",
+            "--fetch-timeout=10000",
+        ]);
+        if (!response.ok)
+            return response;
+        try {
+            const parsed = z.string().min(1).safeParse(JSON.parse(response.value));
+            return parsed.success
+                ? ok(parsed.data)
+                : err(`Invalid npm release metadata: ${parsed.error.message}`);
+        }
+        catch (cause) {
+            return err(cause instanceof Error ? cause.message : String(cause));
+        }
+    },
+    installVersion: async (installation, version, output) => {
+        const result = await runUpdateCommand(updateInstallCommand(installation, version), output);
+        return result.ok ? ok(undefined) : result;
+    },
+    installedVersion: (installation) => runUpdateCommand([
+        process.execPath,
+        join(installation.packageRoot, "scripts", "rea.mjs"),
+        "--version",
+    ]),
+    planMaintenance: (installation) => planIntegrationMaintenance(home, join(installation.packageRoot, "scripts", "rea.mjs"), runUpdateCommand),
+});

package/dist/application/runtime.js

@@ -4,7 +4,10 @@ import { silentLogger } from "../logger.js";
 import { GENERATED_AUXILIARY_PROVIDERS } from "../generatedMcpToolCatalog.js";
 import { AnalysisProviderRegistry } from "./AnalysisProviderRegistry.js";
 import { composeBinarySession } from "./BinarySessionComposition.js";
+import { nativeHostCapabilities } from "../native/NativeHostCapabilities.js";
 import { LazyAnalysisProvider } from "./LazyAnalysisProvider.js";
+import { ManagedStaticProvider } from "../dotnet/ManagedStaticProvider.js";
+import { SessionProviderRouter } from "./SessionProviderRouter.js";
 /**
  * Compose the target-switching runtime shared directly by CLI and MCP adapters.
  * This is the sole production wiring point, so both adapters share identical
@@ -21,12 +24,16 @@ export const createBinarySession = (config, logger = silentLogger) => {
         const generated = auxiliary.get(id);
         if (generated === undefined)
             throw new TypeError(`Missing generated provider metadata for ${id}`);
-        return new LazyAnalysisProvider({ ...generated, load });
+        return new LazyAnalysisProvider({
+            ...generated,
+            capabilities: nativeHostCapabilities(generated.capabilities),
+            load,
+        });
     };
     return composeBinarySession(new AnalysisProviderRegistry([hopper, ghidra], config.analysisProvider), [
         lazyProvider("rea-artifact-graph", async () => {
             const { ArtifactProvider } = await import("../artifacts/ArtifactProvider.js");
-            return new ArtifactProvider(config.artifactNativeMountEnabled, config.artifactIntegrityContinueEnabled);
+            return new ArtifactProvider();
         }),
         lazyProvider("native-macos", async () => {
             const { NativeMacOSProvider } = await import("../native/NativeMacOSProvider.js");
@@ -38,3 +45,7 @@ export const createBinarySession = (config, logger = silentLogger) => {
         }),
     ]);
 };
+/** Compose an execution-free managed session without native provider selection. */
+export const createManagedBinarySession = () => composeBinarySession(SessionProviderRouter.selectable(new AnalysisProviderRegistry([]), [
+    new ManagedStaticProvider(),
+]));

package/dist/artifacts/ArtifactPaths.js

@@ -19,20 +19,19 @@ export const normalizeArtifactPath = (input) => {
 /** Reject exact, Unicode-normalized, case-folded, and prefix collisions. */
 export class ArtifactPathRegistry {
     #root = { kind: undefined, children: new Map() };
-    #folded = new Set();
     add(path, kind) {
-        const folded = path.toLocaleLowerCase("en-US");
-        if (this.#folded.has(folded))
-            throw new ArtifactReaderFailure("path", `Artifact path collision: ${path}`);
         const parts = path.split("/");
         let node = this.#root;
         for (const [index, part] of parts.entries()) {
             if (node.kind !== undefined && node.kind !== "directory")
                 throw new ArtifactReaderFailure("path", `Artifact prefix conflict: ${path}`);
-            let child = node.children.get(part);
+            const foldedPart = part.toLocaleLowerCase("en-US");
+            let child = node.children.get(foldedPart);
+            if (child !== undefined && child.spelling !== part)
+                throw new ArtifactReaderFailure("path", `Artifact path collision: ${path}`);
             if (child === undefined) {
-                child = { kind: undefined, children: new Map() };
-                node.children.set(part, child);
+                child = { spelling: part, kind: undefined, children: new Map() };
+                node.children.set(foldedPart, child);
             }
             node = child;
             if (index === parts.length - 1) {
@@ -43,6 +42,5 @@ export class ArtifactPathRegistry {
             }
         }
         node.kind = kind;
-        this.#folded.add(folded);
     }
 }

package/dist/artifacts/ArtifactProvider.js

@@ -1,7 +1,10 @@
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { inspectBundleKeyedArchive } from "./KeyedArchiveReader.js";
+import { basename, dirname } from "node:path";
 import { inventoryArtifact } from "../application/ArtifactInventory.js";
 import { extractArtifact } from "../application/ArtifactExtraction.js";
 import { analyzeInterfaceBuilderBundle } from "../application/InterfaceBuilderAnalysis.js";
+import { analyzeAppleAssetCatalogs } from "../application/AppleAssetCatalogAnalysis.js";
 import { ARTIFACT_ANALYSIS_OPERATIONS, artifactInventoryInputSchema, artifactExtractionExecutionSchema, } from "../contracts/artifactToolContracts.js";
 import { AnalysisCapabilityUnavailableError, ArtifactOperationError, } from "../domain/errors.js";
 import { interfaceBuilderLimitsSchema } from "../domain/interfaceBuilderGraph.js";
@@ -10,35 +13,43 @@ import { ArtifactReaderFailure } from "./ArtifactReader.js";
 import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
 import { createEvidence } from "../domain/evidence.js";
 import { createArtifactInspection } from "../domain/artifactInspection.js";
-import { resolveArtifactIntegrityPolicy, resolveNativeMountPolicy, } from "../application/ArtifactInventory/policy.js";
+import { resolveArtifactIntegrityPolicy } from "../application/ArtifactInventory/policy.js";
 const IDENTITY = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
-    nativeMountEnabled;
-    integrityContinueEnabled;
-    constructor(nativeMountEnabled = false, integrityContinueEnabled = false) {
-        this.nativeMountEnabled = nativeMountEnabled;
-        this.integrityContinueEnabled = integrityContinueEnabled;
+    #capabilities;
+    constructor(platform = process.platform) {
+        this.#capabilities = Object.freeze(ARTIFACT_ANALYSIS_OPERATIONS.map((operation) => {
+            const common = {
+                provider: IDENTITY,
+                operation,
+                effects: Object.freeze({
+                    mutatesArtifact: false,
+                    launchesProcess: operation !== "decode_interface_builder" &&
+                        operation !== "inspect_keyed_archive",
+                    mayShowUi: false,
+                    mayAccessNetwork: false,
+                    mayWriteFilesystem: operation === "extract_artifact" ||
+                        operation === "inspect_artifact" ||
+                        operation === "inventory_artifact",
+                    changesPermissions: false,
+                    requiresRoot: false,
+                }),
+                limitations: Object.freeze([
+                    "DMG child inventory automatically uses a read-only native macOS mount; PKG remains root-hash-only.",
+                    "ASAR files discovered in filesystem-backed inventories are expanded without bulk extraction; other nested containers remain recorded only.",
+                ]),
+            };
+            return Object.freeze(operation === "inspect_asset_catalog" && platform !== "darwin"
+                ? {
+                    ...common,
+                    available: false,
+                    availabilityCode: "unsupported_host",
+                    reason: "Apple asset catalogs require macOS assetutil.",
+                }
+                : { ...common, available: true, reason: null });
+        }));
     }
-    #capabilities = Object.freeze(ARTIFACT_ANALYSIS_OPERATIONS.map((operation) => Object.freeze({
-        provider: IDENTITY,
-        operation,
-        available: true,
-        reason: null,
-        effects: Object.freeze({
-            mutatesArtifact: false,
-            launchesProcess: operation !== "decode_interface_builder",
-            mayShowUi: false,
-            mayAccessNetwork: false,
-            mayWriteFilesystem: operation === "extract_artifact",
-            changesPermissions: false,
-            requiresRoot: false,
-        }),
-        limitations: Object.freeze([
-            "DMG child inventory is macOS-only and requires per-call approval plus operator policy; PKG remains root-hash-only.",
-            "ASAR files discovered in filesystem-backed inventories are expanded without bulk extraction; other nested containers remain recorded only.",
-        ]),
-    })));
     identity() {
         return IDENTITY;
     }
@@ -46,17 +57,13 @@ export class ArtifactProvider {
         return this.#capabilities;
     }
     createClient(target) {
-        return new ArtifactClient(target, this.nativeMountEnabled, this.integrityContinueEnabled);
+        return new ArtifactClient(target);
     }
 }
 class ArtifactClient {
     target;
-    nativeMountEnabled;
-    integrityContinueEnabled;
-    constructor(target, nativeMountEnabled, integrityContinueEnabled) {
+    constructor(target) {
         this.target = target;
-        this.nativeMountEnabled = nativeMountEnabled;
-        this.integrityContinueEnabled = integrityContinueEnabled;
     }
     async execute(operation, parameters, options) {
         if (operation === "health")
@@ -88,6 +95,37 @@ class ArtifactClient {
                     })),
                 }));
             }
+            if (operation === "inspect_keyed_archive") {
+                const standalone = this.target.kind === "artifact" && this.target.format === "plist";
+                if (standalone &&
+                    parameters.path !== undefined &&
+                    parameters.path !== "." &&
+                    parameters.path !== basename(this.target.path))
+                    throw new ArtifactReaderFailure("path", "For an active plist, path must select that archive (omit path or use its basename)");
+                const bundlePath = standalone
+                    ? dirname(this.target.path)
+                    : this.target.sourcePath;
+                if (bundlePath === undefined ||
+                    (!standalone && !bundlePath.toLowerCase().endsWith(".app")))
+                    throw new ArtifactReaderFailure("unavailable", "inspect_keyed_archive requires an active plist or .app bundle");
+                const result = await inspectBundleKeyedArchive({
+                    bundlePath,
+                    targetSha256: this.target.sha256,
+                    parameters: standalone
+                        ? { ...parameters, path: basename(this.target.path) }
+                        : parameters,
+                    ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                });
+                if (standalone && result.archive_sha256 !== this.target.sha256)
+                    throw new ArtifactReaderFailure("integrity", `Active archive digest changed: expected ${this.target.sha256}, observed ${result.archive_sha256}`);
+                return ok(createAnalysisExecution(result, IDENTITY, {
+                    limitations: result.limitations,
+                    locations: [{ kind: "artifact-path", path: result.archive_path }],
+                }));
+            }
+            if (operation === "inspect_asset_catalog") {
+                return await this.inspectAssetCatalog(parameters, options);
+            }
             if (operation === "extract_artifact") {
                 const parsed = artifactExtractionExecutionSchema.parse(parameters);
                 const result = await extractArtifact({
@@ -124,13 +162,31 @@ class ArtifactClient {
     close() {
         return Promise.resolve();
     }
+    async inspectAssetCatalog(parameters, options) {
+        const bundlePath = this.target.sourcePath;
+        if (this.target.kind !== "executable" ||
+            bundlePath === undefined ||
+            !bundlePath.toLowerCase().endsWith(".app"))
+            throw new ArtifactReaderFailure("unavailable", "inspect_asset_catalog requires an active .app bundle target");
+        const result = await analyzeAppleAssetCatalogs({
+            bundlePath,
+            targetSha256: this.target.sha256,
+            page: parameters,
+            ...(options?.signal === undefined ? {} : { signal: options.signal }),
+        });
+        return ok(createAnalysisExecution(result, IDENTITY, {
+            limitations: result.limitations,
+            locations: result.catalogs.map(({ path }) => ({
+                kind: "artifact-path",
+                path,
+            })),
+        }));
+    }
     async inspectArtifact(parameters, options) {
         const parsed = artifactInventoryInputSchema.parse(parameters);
-        const inventoryParameters = artifactInventoryInputSchema.parse({
-            native_mount_approved: parsed.native_mount_approved,
+        const inventoryParameters = {
             integrity_policy: parsed.integrity_policy,
-            integrity_continue_approved: parsed.integrity_continue_approved,
-        });
+        };
         await options?.progress?.report({
             phase: "inspect_artifact.inventory",
             completed: 0,
@@ -168,12 +224,9 @@ class ArtifactClient {
     inventory(parsed, options) {
         return inventoryArtifact(this.target.sourcePath ?? this.target.path, {
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
-            nativeMount: resolveNativeMountPolicy(parsed.native_mount_approved === true, this.nativeMountEnabled),
-            integrity: resolveArtifactIntegrityPolicy(parsed.integrity_policy === "fail"
-                ? { mode: "fail" }
-                : {
-                    mode: parsed.integrity_policy,
-                }, this.integrityContinueEnabled),
+            integrity: resolveArtifactIntegrityPolicy({
+                mode: parsed.integrity_policy,
+            }),
         });
     }
 }

package/dist/artifacts/AsarArtifactReader.js

@@ -1,5 +1,6 @@
+import { sep } from "node:path";
 import { Readable } from "node:stream";
-import { extractFile, listPackage, statFile } from "@electron/asar";
+import { extractFile, listPackage, statFile, uncache } from "@electron/asar";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
 /**
  * Official Electron ASAR adapter. Individual files remain caller-bounded.
@@ -17,6 +18,8 @@ export class AsarArtifactReader {
     async *entries(signal) {
         let paths;
         try {
+            // ASAR caches headers by path even after the archive has been replaced.
+            uncache(this.path);
             paths = listPackage(this.path, { isPack: false }).sort((left, right) => left.localeCompare(right, "en"));
         }
         catch (cause) {
@@ -24,12 +27,19 @@ export class AsarArtifactReader {
         }
         for (const listed of paths) {
             abortIfNeeded(signal);
-            const path = listed.replace(/^\/+|\/+$/gu, "");
+            // @electron/asar returns paths assembled with the host path module.
+            // Keep that spelling for its API calls, but expose archive paths with
+            // portable separators. On POSIX, backslashes can be literal filename
+            // characters and must remain untouched.
+            const path = toArtifactPath(listed);
             if (path.length === 0)
                 continue;
+            const providerPath = listed.startsWith(sep)
+                ? listed.slice(sep.length)
+                : listed;
             let metadata;
             try {
-                metadata = statFile(this.path, path, false);
+                metadata = statFile(this.path, providerPath, false);
             }
             catch (cause) {
                 throw asarFailure(this.path, `stat ${path}`, cause);
@@ -58,7 +68,7 @@ export class AsarArtifactReader {
                     : [
                         "Official ASAR extraction buffers each individually bounded file.",
                     ],
-                adapterKey: path,
+                adapterKey: providerPath,
             };
         }
     }
@@ -81,6 +91,7 @@ export class AsarArtifactReader {
         }
     }
     close() {
+        uncache(this.path);
         return Promise.resolve();
     }
     provenance() {
@@ -91,6 +102,10 @@ const abortIfNeeded = (signal) => {
     if (signal?.aborted === true)
         throw new ArtifactReaderFailure("cancelled", "ASAR operation cancelled");
 };
+const toArtifactPath = (listed) => {
+    const portable = sep === "\\" ? listed.replaceAll("\\", "/") : listed;
+    return portable.replace(/^\/+|\/+$/gu, "");
+};
 const asarFailure = (path, operation, cause) => cause instanceof ArtifactReaderFailure
     ? cause
     : new ArtifactReaderFailure("format", `Malformed or unreadable ASAR during ${operation}: ${path}`, { cause });

package/dist/artifacts/KeyedArchiveReader.js

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { TextDecoder } from "node:util";
+import { parse, parseBinary } from "plist";
+import { z } from "zod";
+import { keyedArchiveInputSchema, keyedArchiveResultSchema, projectKeyedArchive, } from "../domain/keyedArchive.js";
+import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";
+import { ArtifactReaderFailure } from "./ArtifactReader.js";
+const MAX_BYTES = 64 * 1024 * 1024;
+/** Parse inert plist bytes, preserving data and dates with explicit typed values. */
+export const decodeKeyedArchiveBytes = (bytes, selection) => {
+    if (bytes.length > MAX_BYTES)
+        throw new RangeError("Keyed archive exceeds 64 MiB");
+    const binary = bytes.subarray(0, 8).toString("ascii") === "bplist00";
+    const parsed = binary
+        ? parseBinary(bytes)
+        : parse(decodeXmlPlistText(bytes));
+    return {
+        archive_format: binary ? "binary-plist" : "xml-plist",
+        ...projectKeyedArchive(normalizePlist(parsed), selection),
+    };
+};
+const decodeXmlPlistText = (bytes) => {
+    const encoding = bytes[0] === 0xff && bytes[1] === 0xfe
+        ? "utf-16le"
+        : bytes[0] === 0xfe && bytes[1] === 0xff
+            ? "utf-16be"
+            : "utf-8";
+    const text = new TextDecoder(encoding, { fatal: true }).decode(bytes);
+    const declared = /^<\?xml\s[^?]*\bencoding\s*=\s*["']([^"']+)["']/u
+        .exec(text)?.[1]
+        ?.toLowerCase();
+    if (declared !== undefined &&
+        ((encoding !== "utf-8" && declared !== encoding && declared !== "utf-16") ||
+            (encoding === "utf-8" && declared.startsWith("utf-16"))))
+        throw new TypeError("XML encoding declaration disagrees with its bytes");
+    return text;
+};
+const normalizePlist = (value, depth = 0) => {
+    if (depth > 128)
+        throw new RangeError("Plist exceeds 128 nesting levels");
+    if (value instanceof Uint8Array)
+        return {
+            $plist_type: "data",
+            base64: Buffer.from(value).toString("base64"),
+        };
+    if (value instanceof Date)
+        return { $plist_type: "date", iso8601: value.toISOString() };
+    if (Array.isArray(value))
+        return value.map((item) => normalizePlist(item, depth + 1));
+    if (value !== null && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            normalizePlist(item, depth + 1),
+        ]));
+    return z
+        .union([z.string(), z.number().finite(), z.boolean(), z.null()])
+        .parse(value);
+};
+/** Read exactly one regular, contained bundle entry without following symlinks. */
+export const inspectBundleKeyedArchive = async (input) => {
+    const selected = keyedArchiveInputSchema.parse(input.parameters);
+    if (selected.path.startsWith("/") ||
+        selected.path
+            .split("/")
+            .some((part) => part === ".." || part === "." || part.length === 0))
+        throw new ArtifactReaderFailure("path", "Archive path must be a canonical relative bundle path");
+    const reader = new DirectoryArtifactReader(input.bundlePath);
+    try {
+        for await (const entry of reader.entries(input.signal)) {
+            if (entry.path !== selected.path)
+                continue;
+            if (entry.kind !== "file")
+                throw new ArtifactReaderFailure("path", "Archive must be a regular file, not a symlink or directory");
+            if ((entry.declaredSize ?? 0) > MAX_BYTES)
+                throw new ArtifactReaderFailure("limit", "Keyed archive exceeds 64 MiB");
+            const stream = await reader.open(entry, input.signal);
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of stream) {
+                if (input.signal?.aborted) {
+                    stream.destroy();
+                    throw new ArtifactReaderFailure("cancelled", "Archive inspection cancelled");
+                }
+                const bytes = z.instanceof(Buffer).parse(chunk);
+                size += bytes.length;
+                if (size > MAX_BYTES) {
+                    stream.destroy();
+                    throw new ArtifactReaderFailure("limit", "Keyed archive exceeds 64 MiB");
+                }
+                chunks.push(bytes);
+            }
+            const bytes = Buffer.concat(chunks, size);
+            try {
+                return keyedArchiveResultSchema.parse({
+                    target_sha256: input.targetSha256,
+                    archive_path: entry.path,
+                    archive_sha256: createHash("sha256").update(bytes).digest("hex"),
+                    ...decodeKeyedArchiveBytes(bytes, selected),
+                });
+            }
+            catch (cause) {
+                throw new ArtifactReaderFailure(cause instanceof RangeError ? "limit" : "format", "Cannot decode selected Foundation keyed archive", { cause });
+            }
+        }
+        throw new ArtifactReaderFailure("path", `Archive not found in bundle: ${selected.path}`);
+    }
+    finally {
+        await reader.close();
+    }
+};