rea-agents 0.3.0 → 0.4.0

package/dist/application/ReferenceSourceImportPolicy.js

@@ -0,0 +1,73 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import ignore from "ignore";
+import { err, ok } from "../domain/result.js";
+import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
+import { DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS, DEFAULT_REFERENCE_SOURCE_LIMITS, } from "./ReferenceSourceImportTypes.js";
+const failure = (code, message) => ({
+    tag: "reference-source-import",
+    code,
+    message,
+});
+const validLimits = (limits) => Object.values(limits).every((value) => Number.isSafeInteger(value) && value > 0);
+const maximumLimits = (options) => ({
+    maxBytes: options.policy.maxBytes,
+    maxEntries: options.policy.maxEntries,
+    maxDepth: options.policy.maxDepth,
+    maxPathBytes: options.policy.maxPathBytes,
+});
+const clampLimits = (requested, maximum) => ({
+    maxBytes: Math.min(requested.maxBytes, maximum.maxBytes),
+    maxEntries: Math.min(requested.maxEntries, maximum.maxEntries),
+    maxDepth: Math.min(requested.maxDepth, maximum.maxDepth),
+    maxPathBytes: Math.min(requested.maxPathBytes, maximum.maxPathBytes),
+});
+const authorizeRoot = async (requestedRoot, approvedRoots) => {
+    if (approvedRoots.length === 0)
+        return err(failure("policy", "No approved reference source roots"));
+    try {
+        if (!(await stat(requestedRoot)).isDirectory())
+            return err(failure("invalid-root", "Reference source root is not a directory"));
+        const canonicalRoot = await realpath(resolve(requestedRoot));
+        for (const approvedRoot of approvedRoots) {
+            const canonicalApproved = await realpath(resolve(approvedRoot));
+            if (withinRoot(canonicalApproved, canonicalRoot))
+                return ok(canonicalRoot);
+        }
+        return err(failure("policy", "Reference source root is outside approved roots"));
+    }
+    catch {
+        return err(failure("invalid-root", "Reference source root could not be resolved"));
+    }
+};
+const buildIgnored = async (root, excludePaths) => {
+    const ignored = ignore();
+    try {
+        ignored.add(await readFile(join(root, ".gitignore"), "utf8"));
+    }
+    catch {
+        // Missing or unreadable ignore file does not authorize broader access.
+    }
+    ignored.add([...DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS]);
+    for (const path of excludePaths) {
+        ignored.add(path);
+        ignored.add(`${path}/`);
+    }
+    return ignored;
+};
+/** Validate limits, authorize root, and build non-executing path filters. */
+export const prepareReferenceSourceImport = async (options) => {
+    const requested = options.limits ?? DEFAULT_REFERENCE_SOURCE_LIMITS;
+    const maximum = maximumLimits(options);
+    if (!validLimits(requested) || !validLimits(maximum))
+        return err(failure("invalid-limits", "Import limits must be positive integers"));
+    const root = await authorizeRoot(options.root, options.policy.roots);
+    if (!root.ok)
+        return root;
+    return ok({
+        root: root.value,
+        limits: clampLimits(requested, maximum),
+        ignored: await buildIgnored(root.value, options.excludePaths ?? []),
+        secrets: ignore().add([...options.policy.secretPatterns]),
+    });
+};

package/dist/application/ReferenceSourceImportTypes.js

@@ -0,0 +1,18 @@
+export const DEFAULT_REFERENCE_SOURCE_IGNORE_PATTERNS = [
+    ".git/",
+    ".git/hooks/",
+    "node_modules/",
+    "dist/",
+    "build/",
+    "coverage/",
+    "htmlcov/",
+    ".coverage",
+    "*.log",
+];
+export const DEFAULT_REFERENCE_SOURCE_LIMITS = {
+    maxBytes: 16 * 1024 * 1024,
+    maxEntries: 10_000,
+    maxDepth: 32,
+    maxPathBytes: 4_096,
+};
+export const PARSEABLE_REFERENCE_SOURCE_LANGUAGES = new Set(["JavaScript", "TypeScript", "JSX", "TSX"]);

package/dist/application/ReferenceSourceVcsAdapter.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveRef } from "isomorphic-git";
+/**
+ * Read Git metadata for a directory using isomorphic-git.
+ *
+ * No git subprocess or network is used; only the local `.git` object store is read.
+ */
+export const readReferenceSourceVcs = async (root, signal) => {
+    if (isAborted(signal))
+        return { kind: "unknown", head: null, dirty: null };
+    try {
+        await lstat(join(root, ".git"));
+    }
+    catch (cause) {
+        return errorCode(cause) === "ENOENT"
+            ? { kind: "none", head: null, dirty: null }
+            : { kind: "unknown", head: null, dirty: null };
+    }
+    try {
+        const head = await resolveRef({ fs, dir: root, ref: "HEAD" });
+        if (isAborted(signal))
+            return { kind: "unknown", head: null, dirty: null };
+        return { kind: "git", head, dirty: null };
+    }
+    catch {
+        return { kind: "unknown", head: null, dirty: null };
+    }
+};
+const errorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
+    ? String(cause.code)
+    : undefined;
+const isAborted = (signal) => signal?.aborted === true;

package/dist/application/Setup.js

@@ -1,13 +1,19 @@
 import { access, copyFile, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { z } from "zod";
+import writeFileAtomic from "write-file-atomic";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { runDoctor, systemDoctorHost } from "./Doctor.js";
 import { probeHomebrew } from "./homebrew.js";
+import { installLinuxHopper, readLinuxDistribution, } from "./LinuxHopper.js";
 const execFileAsync = promisify(execFile);
+const registrationCommand = () => process.env.npm_command === "exec"
+    ? ["npx", "-y", PRODUCT_IDENTITY.packageName, "mcp"]
+    : [resolve(process.argv[1] ?? PRODUCT_IDENTITY.cliBinary), "mcp"];
 /**
  * Install prerequisites and configure detected clients idempotently.
  * With `yes` false, mutations requiring consent are reported as `needs_human`;
@@ -23,14 +29,10 @@ export const runSetup = async (yes, host = systemSetupHost()) => {
         doctor: await host.doctor(),
         remediation,
     });
-    if (host.platform !== "darwin")
-        return fail("Hopper requires macOS 12 or newer.");
-    const macosVersion = await host.macosVersion();
-    if (macosVersion === undefined || major(macosVersion) < 12)
-        return fail("Upgrade to macOS 12 or newer.");
-    if (major(host.nodeVersion) < 22)
-        return fail("Install Node.js 22 or newer.");
-    if (!(await host.hasHomebrew())) {
+    const unsupported = await hostRemediation(host);
+    if (unsupported !== undefined)
+        return fail(unsupported);
+    if (host.platform === "darwin" && !(await host.hasHomebrew())) {
         if (!yes)
             return fail("Re-run with --yes to install Homebrew.");
         if (!(await host.installHomebrew()))
@@ -49,7 +51,7 @@ export const runSetup = async (yes, host = systemSetupHost()) => {
             return fail("Hopper installation completed but its launcher was not found.");
     }
     for (const client of await host.detectedClients()) {
-        const result = await host.configureClient(client, hopperPath);
+        const result = await host.configureClient(client, hopperPath, registrationCommand());
         clients[client.name] = result;
         if (result.status === "failed")
             return fail(`${client.name} configuration ${result.reason} verification failed; no successful configuration was reported.`);
@@ -62,18 +64,37 @@ export const runSetup = async (yes, host = systemSetupHost()) => {
     if (skill === "installed")
         actions.push("installed_skill");
     const doctor = await host.doctor();
+    const activationRequired = actions.includes("installed_hopper");
+    const ready = doctor.healthy && !activationRequired;
     return {
-        status: doctor.healthy ? "ready" : "needs_human",
+        status: ready ? "ready" : "needs_human",
         actions,
         clients,
         doctor,
-        ...(doctor.healthy
+        ...(ready
             ? {}
             : {
-                remediation: "Run rea doctor and apply each reported remediation.",
+                remediation: activationRequired
+                    ? "Open Hopper, complete its one-time activation, then rerun rea doctor --json."
+                    : "Run rea doctor and apply each reported remediation.",
             }),
     };
 };
+const hostRemediation = async (host) => {
+    if (host.platform !== "darwin" && host.platform !== "linux")
+        return "REA supports Hopper on macOS and selected 64-bit Linux distributions.";
+    if (major(host.nodeVersion) < 24)
+        return "Install Node.js 24.18 or newer.";
+    if (host.platform === "darwin") {
+        const version = await host.macosVersion();
+        return version === undefined || major(version) < 12
+            ? "Upgrade to macOS 12 or newer."
+            : undefined;
+    }
+    return (await host.linuxDistribution())?.supported === true
+        ? undefined
+        : "REA supports Hopper on Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux.";
+};
 /** Production setup effects for macOS, Homebrew, JSON MCP clients, and the canonical skill directory. */
 const systemSetupHost = () => {
     const doctorHost = systemDoctorHost();
@@ -81,40 +102,81 @@ const systemSetupHost = () => {
         platform: process.platform,
         nodeVersion: process.versions.node,
         macosVersion: () => doctorHost.macosVersion(),
+        linuxDistribution: readLinuxDistribution,
         hasHomebrew: () => brewSucceeds(["--version"]),
         installHomebrew: () => commandSucceeds("/bin/bash", [
             "-c",
             "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)",
         ], { ...process.env, NONINTERACTIVE: "1" }),
         hopperPath: async () => (await runDoctor(undefined, doctorHost)).hopperPath,
-        installHopper: () => brewSucceeds(["install", "--cask", "hopper-disassembler"]),
-        detectedClients: () => detectJsonClients(homedir()),
-        configureClient: configureJsonClient,
+        installHopper: () => process.platform === "linux"
+            ? installLinuxHopper().then(({ status }) => status === "installed")
+            : brewSucceeds(["install", "--cask", "hopper-disassembler"]),
+        detectedClients: () => detectClients(homedir()),
+        configureClient: (client, hopperPath, command) => client.format === "unsupported"
+            ? Promise.resolve({ status: "skipped" })
+            : client.format === "toml"
+                ? configureTomlClient(client, hopperPath, command)
+                : configureJsonClient(client, hopperPath, command),
         installSkill: () => installCanonicalSkill(homedir()),
         doctor: () => runDoctor(undefined, doctorHost),
     };
 };
-const detectJsonClients = async (home) => {
-    const candidates = [
-        {
-            name: "claude_desktop",
-            configPath: join(home, "Library/Application Support/Claude/claude_desktop_config.json"),
-            marker: join(home, "Library/Application Support/Claude"),
-        },
-        {
-            name: "cursor",
-            configPath: join(home, ".cursor/mcp.json"),
-            marker: join(home, ".cursor"),
-        },
-    ];
+/** Detect supported coding agents from stable per-user installation markers. */
+export const detectClients = async (home) => {
     const detected = [];
-    for (const candidate of candidates)
-        if (await exists(candidate.marker))
-            detected.push({ name: candidate.name, configPath: candidate.configPath });
+    for (const candidate of supportedClients(home))
+        if (await exists(candidate.markerPath ?? candidate.configPath))
+            detected.push(candidate);
     return detected;
 };
+/** Describe every client location that setup or uninstall may own. */
+export const supportedClients = (home) => [
+    {
+        name: "claude_code",
+        configPath: join(home, ".claude.json"),
+        markerPath: join(home, ".claude"),
+    },
+    {
+        name: "claude_desktop",
+        configPath: join(home, "Library/Application Support/Claude/claude_desktop_config.json"),
+        markerPath: join(home, "Library/Application Support/Claude"),
+    },
+    {
+        name: "codex",
+        configPath: join(home, ".codex/config.toml"),
+        markerPath: join(home, ".codex"),
+        format: "toml",
+    },
+    {
+        name: "cursor",
+        configPath: join(home, ".cursor/mcp.json"),
+        markerPath: join(home, ".cursor"),
+    },
+    {
+        name: "gemini_cli",
+        configPath: join(home, ".gemini/settings.json"),
+        markerPath: join(home, ".gemini"),
+    },
+    {
+        name: "windsurf",
+        configPath: join(home, ".codeium/windsurf/mcp_config.json"),
+        markerPath: join(home, ".codeium/windsurf"),
+    },
+    {
+        name: "devin",
+        configPath: join(home, ".devin"),
+        markerPath: join(home, ".devin"),
+        format: "unsupported",
+    },
+];
 /** Back up, atomically update, and semantically read back one JSON MCP configuration. */
-export const configureJsonClient = async (client, hopperPath) => {
+export const configureJsonClient = async (client, hopperPath, command = [
+    "npx",
+    "-y",
+    PRODUCT_IDENTITY.packageName,
+    "mcp",
+]) => {
     let document = {};
     let original;
     try {
@@ -133,8 +195,8 @@ export const configureJsonClient = async (client, hopperPath) => {
         return { status: "failed", reason: "readback" };
     }
     const desired = {
-        command: "npx",
-        args: ["-y", PRODUCT_IDENTITY.packageName, "mcp"],
+        command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
+        args: command.slice(1),
         ...(hopperPath === undefined
             ? {}
             : { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
@@ -184,19 +246,108 @@ export const configureJsonClient = async (client, hopperPath) => {
         ...(backupPath === undefined ? {} : { backupPath }),
     };
 };
-const installCanonicalSkill = async (home) => {
+/** Back up, atomically update, and semantically read back Codex TOML configuration. */
+export const configureTomlClient = async (client, hopperPath, command = [
+    "npx",
+    "-y",
+    PRODUCT_IDENTITY.packageName,
+    "mcp",
+]) => {
+    let document = {};
+    let original;
+    try {
+        original = await readFile(client.configPath, "utf8");
+        document = objectSchema.parse(parseToml(original));
+    }
+    catch (cause) {
+        if (!isMissing(cause))
+            return { status: "failed", reason: "readback" };
+    }
+    let servers;
+    try {
+        servers = parseOptionalObject(document.mcp_servers);
+    }
+    catch {
+        return { status: "failed", reason: "readback" };
+    }
+    const desired = {
+        command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
+        args: command.slice(1),
+        ...(hopperPath === undefined
+            ? {}
+            : { env: { HOPPER_LAUNCHER_PATH: hopperPath } }),
+    };
+    if (JSON.stringify(servers[PRODUCT_IDENTITY.mcpServerKey]) ===
+        JSON.stringify(desired))
+        return { status: "unchanged" };
+    const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
+    try {
+        if (backupPath !== undefined)
+            await copyFile(client.configPath, backupPath);
+    }
+    catch {
+        return { status: "failed", reason: "backup" };
+    }
+    document.mcp_servers = {
+        ...servers,
+        [PRODUCT_IDENTITY.mcpServerKey]: desired,
+    };
+    try {
+        await mkdir(dirname(client.configPath), { recursive: true });
+        await writeFileAtomic(client.configPath, stringifyToml(document), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        const readback = objectSchema.parse(parseToml(await readFile(client.configPath, "utf8")));
+        if (JSON.stringify(parseOptionalObject(readback.mcp_servers)[PRODUCT_IDENTITY.mcpServerKey]) !== JSON.stringify(desired))
+            throw new Error("TOML readback mismatch");
+    }
+    catch {
+        await restoreConfig(client.configPath, original);
+        return { status: "failed", reason: "readback" };
+    }
+    return {
+        status: "configured",
+        ...(backupPath === undefined ? {} : { backupPath }),
+    };
+};
+/** Transactionally install or upgrade the versioned canonical REA skill. */
+export const installCanonicalSkill = async (home) => {
     const destination = join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md");
+    const backup = `${destination}.rea.backup`;
+    let original;
     try {
         const content = await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, import.meta.url), "utf8");
-        if ((await readFile(destination, "utf8").catch(() => undefined)) === content)
+        original = await readFile(destination, "utf8").catch(() => undefined);
+        if (original === content)
             return "unchanged";
         await mkdir(dirname(destination), { recursive: true });
-        await writeFile(destination, content, { encoding: "utf8", mode: 0o600 });
-        return (await readFile(destination, "utf8")) === content
-            ? "installed"
-            : "failed";
+        if (original !== undefined)
+            await writeFileAtomic(backup, original, {
+                encoding: "utf8",
+                mode: 0o600,
+            });
+        await writeFileAtomic(destination, content, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        if ((await readFile(destination, "utf8")) !== content)
+            throw new Error("skill readback mismatch");
+        return "installed";
     }
     catch {
+        try {
+            if (original === undefined)
+                await rm(destination, { force: true });
+            else
+                await writeFileAtomic(destination, original, {
+                    encoding: "utf8",
+                    mode: 0o600,
+                });
+        }
+        catch {
+            // The backup remains beside the skill for explicit operator recovery.
+        }
         return "failed";
     }
 };

package/dist/application/Uninstall.js

@@ -0,0 +1,130 @@
+import { copyFile, lstat, readFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join } from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import writeFileAtomic from "write-file-atomic";
+import { z } from "zod";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { supportedClients } from "./Setup.js";
+/** Remove only REA-owned registrations and managed files, optionally including local state. */
+export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
+    const items = [];
+    for (const client of await host.clients())
+        items.push(await host.removeClient(client));
+    items.push(await host.removeSkill());
+    if (purgeData)
+        items.push(...(await host.purgeData()));
+    items.push({
+        name: "analysis_engine",
+        status: "retained",
+        detail: "Hopper is not owned by REA uninstall.",
+    });
+    return {
+        status: items.some(({ status }) => status === "failed")
+            ? "failed"
+            : "complete",
+        items,
+    };
+};
+/** Create uninstall effects contained to detected client configs and REA-owned paths. */
+export const systemUninstallHost = (home = homedir()) => ({
+    clients: () => Promise.resolve(supportedClients(home)),
+    removeClient,
+    removeSkill: () => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill"),
+    purgeData: async () => [
+        await removeManagedPath(join(home, ".rea/cache"), "cache"),
+        await removeManagedPath(join(home, ".rea/state"), "state"),
+    ],
+});
+const removeClient = async (client) => {
+    if (client.format === "unsupported")
+        return item(client.name, "skipped", "This client has no documented local MCP configuration boundary.");
+    let original;
+    try {
+        original = await readFile(client.configPath, "utf8");
+    }
+    catch (cause) {
+        return isMissing(cause)
+            ? item(client.name, "skipped", "Configuration does not exist.")
+            : item(client.name, "failed", "Configuration could not be read.");
+    }
+    let document;
+    let key;
+    let servers;
+    try {
+        document = objectSchema.parse(client.format === "toml" ? parseToml(original) : JSON.parse(original));
+        key = client.format === "toml" ? "mcp_servers" : "mcpServers";
+        servers = optionalObject(document[key]);
+    }
+    catch {
+        return item(client.name, "failed", "Malformed configuration was preserved without mutation.");
+    }
+    const registration = servers[PRODUCT_IDENTITY.mcpServerKey];
+    if (registration === undefined)
+        return item(client.name, "skipped", "REA registration is absent.");
+    if (!isOwnedRegistration(registration))
+        return item(client.name, "retained", "The rea-named registration is not REA-owned.");
+    const remaining = { ...servers };
+    delete remaining[PRODUCT_IDENTITY.mcpServerKey];
+    document[key] = remaining;
+    const backupPath = `${client.configPath}.rea.backup`;
+    try {
+        await copyFile(client.configPath, backupPath);
+    }
+    catch {
+        return item(client.name, "failed", "Configuration backup failed; no mutation was attempted.");
+    }
+    try {
+        const encoded = client.format === "toml"
+            ? stringifyToml(document)
+            : `${JSON.stringify(document, null, 2)}\n`;
+        await writeFileAtomic(client.configPath, encoded, { encoding: "utf8" });
+        const readback = objectSchema.parse(client.format === "toml"
+            ? parseToml(await readFile(client.configPath, "utf8"))
+            : JSON.parse(await readFile(client.configPath, "utf8")));
+        if (PRODUCT_IDENTITY.mcpServerKey in optionalObject(readback[key]))
+            throw new Error("registration readback mismatch");
+        return item(client.name, "removed", `Removed registration from ${client.configPath}.`);
+    }
+    catch {
+        await writeFileAtomic(client.configPath, original, {
+            encoding: "utf8",
+        }).catch(() => undefined);
+        return item(client.name, "failed", `Configuration update failed; the original was restored and ${backupPath} was retained.`);
+    }
+};
+/** Ownership rule for persistent MCP registrations created by REA setup. */
+const isOwnedRegistration = (value) => {
+    const parsed = registrationSchema.safeParse(value);
+    if (!parsed.success)
+        return false;
+    const { command, args } = parsed.data;
+    return (((command === "rea" ||
+        (isAbsolute(command) && basename(command) === "rea")) &&
+        args.length === 1 &&
+        args[0] === "mcp") ||
+        (command === "npx" &&
+            JSON.stringify(args) ===
+                JSON.stringify(["-y", PRODUCT_IDENTITY.packageName, "mcp"])));
+};
+const removeManagedPath = async (path, name) => {
+    try {
+        const stats = await lstat(path);
+        if (stats.isSymbolicLink())
+            return item(name, "retained", `Refused to follow symlink ${path}.`);
+        await rm(path, { recursive: true });
+        return item(name, "removed", `Removed ${path}.`);
+    }
+    catch (cause) {
+        return isMissing(cause)
+            ? item(name, "skipped", `${path} does not exist.`)
+            : item(name, "failed", `${path} could not be removed.`);
+    }
+};
+const item = (name, status, detail) => ({ name, status, detail });
+const objectSchema = z.record(z.string(), z.unknown());
+const optionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);
+const registrationSchema = z
+    .object({ command: z.string(), args: z.array(z.string()) })
+    .passthrough();
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";

package/dist/application/runtime.js

@@ -1,5 +1,8 @@
 import { BinarySession } from "./BinarySession.js";
 import { HopperProvider } from "../hopper/HopperProvider.js";
+import { NativeMacOSProvider } from "../native/NativeMacOSProvider.js";
+import { ArtifactProvider } from "../artifacts/ArtifactProvider.js";
+import { CompositeProvider } from "./CompositeProvider.js";
 import { silentLogger } from "../logger.js";
 /**
  * Compose the target-switching runtime shared directly by CLI and MCP adapters.
@@ -7,5 +10,9 @@ import { silentLogger } from "../logger.js";
  * out to the other and both retain identical loader and bridge semantics.
  */
 export const createBinarySession = (config, logger = silentLogger) => {
-    return new BinarySession(new HopperProvider(config, logger));
+    return new BinarySession(new CompositeProvider([
+        new ArtifactProvider(),
+        new NativeMacOSProvider(),
+        new HopperProvider(config, logger),
+    ]));
 };

package/dist/artifacts/ArtifactPaths.js

@@ -0,0 +1,51 @@
+import { Buffer } from "node:buffer";
+import { posix } from "node:path";
+import { ArtifactReaderFailure, } from "./ArtifactReader.js";
+const DRIVE_OR_UNC = /^(?:[A-Za-z]:|\\|\/\/)/u;
+/** Normalize an untrusted logical archive path without touching filesystem. */
+export const normalizeArtifactPath = (input, limits) => {
+    if (input.includes("\0") ||
+        input.includes("\\") ||
+        input.startsWith("/") ||
+        DRIVE_OR_UNC.test(input))
+        throw new ArtifactReaderFailure("path", "Artifact path is absolute or unsafe");
+    const normalized = input.normalize("NFC").replace(/\/+$/u, "");
+    const parts = normalized.split("/");
+    if (normalized.length === 0 ||
+        parts.some((part) => part === "" || part === "." || part === "..") ||
+        parts.length > limits.maxDepth ||
+        Buffer.byteLength(normalized, "utf8") > limits.maxPathBytes ||
+        posix.normalize(normalized) !== normalized)
+        throw new ArtifactReaderFailure("path", "Artifact path is not normalized");
+    return normalized;
+};
+/** 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);
+            if (child === undefined) {
+                child = { kind: undefined, children: new Map() };
+                node.children.set(part, child);
+            }
+            node = child;
+            if (index === parts.length - 1) {
+                if (node.kind !== undefined)
+                    throw new ArtifactReaderFailure("path", `Artifact path collision: ${path}`);
+                if (kind !== "directory" && node.children.size > 0)
+                    throw new ArtifactReaderFailure("path", `Artifact prefix conflict: ${path}`);
+            }
+        }
+        node.kind = kind;
+        this.#folded.add(folded);
+    }
+}