comisai 1.0.37 → 1.0.40

package/node_modules/@comis/skills/dist/builtin/file-tools/write-tool.js

@@ -1,283 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Native write tool: file creation and overwrite with read-before-write
- * enforcement, staleness detection, encoding preservation, path safety,
- * and FileStateTracker integration.
- *
- * Replaces pi-mono createWriteTool + wrapper stack with a single
- * self-contained factory. Follows the edit-tool.ts pattern.
- *
- * @module
- */
-import { Type } from "typebox";
-import * as fs from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { basename, dirname, extname } from "node:path";
-import { fromPromise } from "@comis/shared";
-import { safePath, PathTraversalError } from "@comis/core";
-import { isDeviceFile } from "../file/file-state-tracker.js";
-import { PROTECTED_WORKSPACE_FILES, resolvePaths, } from "../file/safe-path-wrapper.js";
-import { readStringParam, readBooleanParam, } from "../platform/tool-helpers.js";
-import { readFileWithMetadata, writeFilePreserving, } from "./shared/file-encoding.js";
-import { validateConfigContent } from "./shared/edit-diff.js";
-import { getGitDiffStat } from "./shared/git-diff.js";
-import { withFileMutationQueue } from "./shared/file-mutation-queue.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/** Maximum file size in bytes (1 GiB). Existing files above this are rejected. */
-const MAX_FILE_SIZE = 1024 * 1024 * 1024;
-// ---------------------------------------------------------------------------
-// Parameter schema
-// ---------------------------------------------------------------------------
-const WriteParams = Type.Object({
-    path: Type.String({
-        description: "Path to the file to create or overwrite (relative to workspace or absolute)",
-    }),
-    content: Type.String({
-        description: "The full content to write to the file",
-    }),
-    createDirectories: Type.Optional(Type.Boolean({
-        description: "Create parent directories if they don't exist (default: true)",
-        default: true,
-    })),
-}, { additionalProperties: false });
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-/**
- * Format byte size as human-readable string.
- * Examples: "512B", "4.1KB", "1.3MB", "1.1GB"
- */
-function formatSize(bytes) {
-    if (bytes < 1024)
-        return `${bytes}B`;
-    if (bytes < 1024 * 1024) {
-        const kb = bytes / 1024;
-        return `${kb < 10 ? kb.toFixed(1) : Math.round(kb)}KB`;
-    }
-    if (bytes < 1024 * 1024 * 1024) {
-        const mb = bytes / (1024 * 1024);
-        return `${mb < 10 ? mb.toFixed(1) : Math.round(mb)}MB`;
-    }
-    const gb = bytes / (1024 * 1024 * 1024);
-    return `${gb < 10 ? gb.toFixed(1) : Math.round(gb)}GB`;
-}
-/**
- * Resolve a write path through the workspace -> sharedPaths fallback chain.
- * Returns the resolved absolute path.
- *
- * Unlike resolveReadPath, write does NOT fall back to readOnlyPaths.
- * Only workspace and sharedPaths are valid targets for writes.
- *
- * Throws Error with [path_traversal] prefix when the path cannot be resolved
- * through any allowed root.
- */
-function resolveWritePath(workspacePath, filePath, sharedPaths) {
-    // Try workspace first
-    try {
-        return safePath(workspacePath, filePath);
-    }
-    catch (error) {
-        if (!(error instanceof PathTraversalError))
-            throw error;
-    }
-    // Try sharedPaths (lazily resolved)
-    const resolved = resolvePaths(sharedPaths);
-    for (const sp of resolved) {
-        try {
-            return safePath(sp, filePath);
-        }
-        catch (error) {
-            if (!(error instanceof PathTraversalError))
-                throw error;
-        }
-    }
-    throw new Error(`[path_traversal] Path outside workspace bounds: ${filePath}`);
-}
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-/**
- * Create the native write tool.
- *
- * Returns an AgentTool that creates new files or overwrites existing files
- * with read-before-write enforcement, staleness detection, encoding
- * preservation, path safety, and FileStateTracker integration.
- *
- * @param workspacePath - Workspace root directory (all relative paths resolve against this)
- * @param logger - Optional pino-compatible logger
- * @param tracker - Optional FileStateTracker for read-before-write and staleness
- * @param sharedPaths - Optional shared paths (lazily resolved) accessible by all tools
- */
-export function createComisWriteTool(workspacePath, logger, tracker, sharedPaths) {
-    // Comis extension: promptGuidelines (not part of AgentTool type, spread to bypass excess property check)
-    const ext = { promptGuidelines: [
-            "For existing files, you MUST read before writing in each response (reads from prior messages do not carry over). Use the edit tool for targeted replacements instead of full rewrites.",
-            "Prefer edit over write for modifying existing files — it only sends the diff.",
-        ] };
-    return {
-        ...ext,
-        name: "write",
-        label: "Write",
-        description: "Create a new file or overwrite an existing file. For new files, parent directories " +
-            "are created automatically. For existing files, you must read the file first in the " +
-            "current response (reads from previous messages do not carry over). " +
-            "The file content is written exactly as provided. Use the edit tool for targeted text " +
-            "replacements instead of rewriting entire files.",
-        parameters: WriteParams,
-        async execute(_toolCallId, params) {
-            // --- V1: Extract params ---
-            const filePath = readStringParam(params, "path");
-            const content = readStringParam(params, "content", false) ?? "";
-            const createDirs = readBooleanParam(params, "createDirectories", false) ?? true;
-            if (!filePath) {
-                throw new Error("[missing_path] path parameter is required");
-            }
-            // --- V2: Path resolution (workspace -> sharedPaths) ---
-            const absolutePath = resolveWritePath(workspacePath, filePath, sharedPaths);
-            // --- V3: Device file blocking ---
-            if (isDeviceFile(absolutePath)) {
-                throw new Error(`[device_file] Cannot write to device file: ${absolutePath}. Hint: Use exec tool to interact with device files if needed.`);
-            }
-            // --- V3.1: Protected workspace file check ---
-            const base = basename(absolutePath);
-            const redirect = PROTECTED_WORKSPACE_FILES.get(base);
-            if (redirect) {
-                throw new Error(`[protected_file] Cannot write to ${base}. Use ${redirect} instead.`);
-            }
-            // --- V3.2: Jupyter notebook rejection ---
-            if (extname(absolutePath).toLowerCase() === ".ipynb") {
-                throw new Error("[jupyter_rejected] Cannot overwrite Jupyter notebooks with the write tool. Use the notebook_edit tool instead for cell-level operations.");
-            }
-            // --- V4: Check existence ---
-            const exists = existsSync(absolutePath);
-            // --- Wrap file mutation in queue for per-path serialization ---
-            const resultData = await withFileMutationQueue(absolutePath, async () => {
-                // Declared outside the `exists` branch so the !exists path can still
-                // return them uniformly (always false/undefined for new files).
-                let coldRead = false;
-                let auditNotice;
-                if (exists) {
-                    // --- V5: File size limit (1 GiB) ---
-                    const stat = await fs.stat(absolutePath);
-                    if (stat.size > MAX_FILE_SIZE) {
-                        throw new Error(`[file_too_large] Existing file too large (${formatSize(stat.size)}). Maximum: 1 GiB`);
-                    }
-                    // --- V6: Cold-register-on-write ---
-                    // Prior behavior threw a read-before-write error when the tracker did
-                    // not contain the path. Root cause: the per-turn tracker was empty at
-                    // session start, so files the LLM legitimately knows (system-prompt
-                    // templates, cross-turn memory) got blocked. Now that the tracker is
-                    // session-lifetime (see session-tracker-registry.ts), the safer
-                    // behavior is: if tracker is missing the path but the file exists,
-                    // read it under the same mutex, register it, and let the downstream
-                    // staleness check (V7) run. Safety is preserved: if an external
-                    // writer mutated the file between our stat above and the cold-register
-                    // read, the staleness compare will fire [stale_file].
-                    if (tracker && !tracker.hasBeenRead(absolutePath)) {
-                        const currentContent = await fs.readFile(absolutePath);
-                        tracker.recordRead(absolutePath, stat.mtimeMs, 0, undefined, currentContent);
-                        coldRead = true;
-                        logger?.debug?.("Cold-registered existing file during write (no prior tracker entry)", { path: absolutePath, sizeBytes: stat.size, reason: "cold-register-on-write" });
-                        // Build audit notice appended to the tool result so the LLM observes
-                        // that it just overwrote a file it hadn't explicitly read this session.
-                        const PREVIEW_MAX = 500;
-                        const previewBuf = currentContent.subarray(0, PREVIEW_MAX);
-                        const truncatedBytes = currentContent.length - previewBuf.length;
-                        const previewText = previewBuf.toString("utf-8");
-                        const truncatedSuffix = truncatedBytes > 0
-                            ? `\n... (truncated, ${truncatedBytes} more bytes)`
-                            : "";
-                        auditNotice =
-                            `Note: wrote to existing file without a prior read in this session. ` +
-                                `Previous content (${formatSize(currentContent.length)}) overwritten. ` +
-                                `First ${Math.min(PREVIEW_MAX, currentContent.length)} bytes were:\n` +
-                                `---\n${previewText}${truncatedSuffix}\n---`;
-                    }
-                    // --- V7: Staleness check (runs even after cold-register to catch external racers) ---
-                    // IMPORTANT: re-stat the file so checkStaleness compares recorded
-                    // mtime against the CURRENT on-disk mtime, not the pre-cold-register
-                    // mtime captured above. Without re-stat, an external writer that
-                    // mutated the file between V5 (initial stat) and here would slip
-                    // past the safety gate because we'd feed the stale mtime in as the
-                    // "current" mtime. Cold-register records `stat.mtimeMs` from V5;
-                    // checkStaleness must see the fresh mtime to detect the race.
-                    if (tracker) {
-                        const freshStat = await fs.stat(absolutePath);
-                        const currentContent = await fs.readFile(absolutePath);
-                        const staleness = tracker.checkStaleness(absolutePath, freshStat.mtimeMs, currentContent);
-                        if (staleness.stale) {
-                            throw new Error("[stale_file] File was modified since you last read it (mtime changed). Re-read before overwriting.");
-                        }
-                    }
-                    // --- V7.1: Config syntax validation ---
-                    const ext = extname(absolutePath).toLowerCase();
-                    const configError = validateConfigContent(ext, content);
-                    if (configError) {
-                        throw new Error(`[invalid_config] ${configError}`);
-                    }
-                    // --- V8: Overwrite: preserve encoding ---
-                    // CRITICAL: Pass LF-normalized content directly to writeFilePreserving.
-                    // Do NOT call restoreLineEndings separately -- writeFilePreserving handles it internally.
-                    // Double-restoration corrupts CRLF files (see PITFALLS.md).
-                    const metadata = await readFileWithMetadata(absolutePath);
-                    await writeFilePreserving(absolutePath, content, metadata.encoding, metadata.lineEnding);
-                }
-                else {
-                    // --- New file path ---
-                    // --- V9: Create parent directories ---
-                    if (createDirs) {
-                        const dir = dirname(absolutePath);
-                        const mkdirResult = await fromPromise(fs.mkdir(dir, { recursive: true }));
-                        if (!mkdirResult.ok) {
-                            throw new Error(`[dir_create_failed] Failed to create directory: ${mkdirResult.error}`);
-                        }
-                    }
-                    // --- V10: Write new file ---
-                    const writeResult = await fromPromise(fs.writeFile(absolutePath, content, "utf-8"));
-                    if (!writeResult.ok) {
-                        throw new Error(`[write_error] Failed to write file: ${writeResult.error}`);
-                    }
-                }
-                // --- Post-write: record in tracker with content hash (both paths converge here) ---
-                const newStat = await fs.stat(absolutePath);
-                const writtenContent = Buffer.from(content, "utf-8");
-                tracker?.recordRead(absolutePath, newStat.mtimeMs, undefined, undefined, writtenContent);
-                return {
-                    path: absolutePath,
-                    created: !exists,
-                    sizeBytes: newStat.size,
-                    coldRead,
-                    auditNotice,
-                };
-            });
-            const gitStat = await getGitDiffStat(absolutePath, workspacePath);
-            const resultText = JSON.stringify({
-                path: resultData.path,
-                created: resultData.created,
-                sizeBytes: resultData.sizeBytes,
-            });
-            const output = gitStat ? `${resultText}\n\n${gitStat}` : resultText;
-            // Build the multi-block tool result. A second "text" block carries the
-            // cold-register audit notice when present, so the LLM sees it inline
-            // with the success result instead of buried in a warning log.
-            const resultBlocks = [
-                { type: "text", text: output },
-            ];
-            if (resultData.auditNotice) {
-                resultBlocks.push({ type: "text", text: resultData.auditNotice });
-            }
-            return {
-                content: resultBlocks,
-                details: {
-                    path: resultData.path,
-                    created: resultData.created,
-                    sizeBytes: resultData.sizeBytes,
-                    coldRead: resultData.coldRead,
-                    gitDiff: gitStat ?? undefined,
-                },
-            };
-        },
-    };
-}

package/node_modules/@comis/skills/dist/builtin/install-detour.js

@@ -1,342 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Install-detour parser: detect pip/npm/pnpm/yarn install commands that
- * overlap connected MCP servers or visible prompt skills.
- *
- * Pure parser — no IO, no per-call state beyond inputs. Returns `null` on
- * parser-bail (unbalanced quotes, no install form found, no overlap detected)
- * to signal "let the command run unchanged."
- *
- * Consumed by:
- * - packages/skills/src/builtin/exec-tool.ts (mode policy gate)
- * - packages/skills/src/builtin/process-tool.ts (advise-mode retroactive hint)
- * - packages/skills/src/builtin/process-registry.ts (InstallDetourDecision type for ProcessSession field)
- *
- * Privacy invariant: the parser produces only sanitized identifiers
- * (`commandDigest`, `packages[].normalizedName`, `overlaps[].sourceName`).
- * Raw command text NEVER leaves this module.
- *
- * @module
- */
-import { createHash } from "node:crypto";
-import { ShellQuoteTracker } from "./exec-security.js";
-// --------------------------------------------------------------------------
-// Public entry point
-// --------------------------------------------------------------------------
-/**
- * Parse a shell command for install-detour overlap. Pure function — no IO,
- * no module state, no memoization. Built fresh per call from the port's
- * runtime state to avoid the skill-visibility race.
- *
- * Returns `null` when:
- * - `splitTopLevelSegments` bails (unbalanced quotes anywhere)
- * - No top-level segment matches the leading-token rule
- * - The matched segment yields no parsed packages after token classification
- * - `overlaps.length === 0` (no detected overlap)
- *
- * @param command - Raw shell command (caller passes verbatim — parser does not sanitize)
- * @param port - ToolCapabilityPort (runtime view of connected servers + visible skills)
- */
-export function parseInstallDetour(command, port) {
-    const segments = splitTopLevelSegments(command);
-    if (segments === null)
-        return null; // unbalanced quotes
-    // Try each top-level segment until one matches an install form
-    for (const segment of segments) {
-        const parsed = parseInstallSegment(segment);
-        if (parsed === null)
-            continue;
-        const { packageManager, rawPackages } = parsed;
-        // Token classification: drop URL/VCS/path/file specs; strip versions; keep registry names
-        const ecosystem = packageManager === "pip" ? "python" : "node";
-        const cleanedNames = [];
-        for (const tok of rawPackages) {
-            const cleaned = classifyPackageToken(tok, ecosystem);
-            if (cleaned !== null)
-                cleanedNames.push(cleaned);
-        }
-        if (cleanedNames.length === 0)
-            continue; // no install-target tokens
-        // Normalize names per ecosystem
-        const normalize = ecosystem === "python" ? normalizePythonName : normalizeNpmName;
-        const packages = [...new Set(cleanedNames.map(normalize))].sort();
-        if (packages.length === 0)
-            continue;
-        // Build alias map FRESH per call — no memoization (avoids skill-visibility race)
-        const { pythonAliases, npmAliases } = buildPackageAliasMap(port);
-        const aliasMap = ecosystem === "python" ? pythonAliases : npmAliases;
-        const connectedServersNorm = new Set(port.getConnectedMcpServers().map(normalize));
-        // Detect overlaps for each package: direct-server first, then alias-map
-        const overlaps = [];
-        for (const pkgN of packages) {
-            if (connectedServersNorm.has(pkgN)) {
-                // Find the original (un-normalized) server name for the sourceName field
-                const serverName = port.getConnectedMcpServers().find((s) => normalize(s) === pkgN);
-                if (serverName) {
-                    const hint = port.getMcpServerHint(serverName);
-                    overlaps.push({
-                        packageName: pkgN,
-                        sourceType: "mcp",
-                        sourceName: serverName,
-                        cluster: hint?.cluster,
-                        reason: "direct-server-name",
-                    });
-                    continue;
-                }
-            }
-            const aliasHit = aliasMap.get(pkgN);
-            if (aliasHit)
-                overlaps.push(aliasHit);
-        }
-        if (overlaps.length === 0)
-            return null; // no overlap → no event → run unchanged
-        // First-match-wins on segments: return on the first segment producing overlap
-        return {
-            packageManager,
-            packages,
-            overlaps,
-            commandDigest: buildCommandDigest(packageManager, packages),
-        };
-    }
-    return null; // no segment matched an install form
-}
-// --------------------------------------------------------------------------
-// Private helpers (NOT exported — internal to install-detour module)
-// --------------------------------------------------------------------------
-/**
- * Split a command on top-level `;` `&&` `||` `|` `&` (outside quotes). Reuses
- * `ShellQuoteTracker` from `exec-security.ts:21-74`. Returns `null` on
- * unbalanced quotes anywhere — the parser-bail signal.
- *
- * Deliberately separate from `exec-security.ts:splitCommandSegments`:
- * - Splits on `&` AS WELL — POSIX background-and-continue is a command terminator
- *   (same operator class as `;`). See exec-security.ts:184 for the canonical reference.
- * - Returns `null` on unbalanced quotes (vs returning collected-so-far).
- * Two helpers, no shared abstraction (KISS-consistent).
- */
-function splitTopLevelSegments(command) {
-    const tracker = new ShellQuoteTracker();
-    const segments = [];
-    let current = "";
-    for (let i = 0; i < command.length; i++) {
-        const ch = command[i];
-        if (!tracker.escaped && tracker.state === "NORMAL") {
-            // Two-char operators first
-            if (i + 1 < command.length) {
-                const two = ch + command[i + 1];
-                if (two === "&&" || two === "||") {
-                    segments.push(current.trim());
-                    current = "";
-                    i++; // skip second char
-                    continue;
-                }
-            }
-            // Single-char operators. `&` is a POSIX command terminator (background-and-continue),
-            // same class as `;` — see exec-security.ts:184. The two-char `&&` lookahead above
-            // runs first, so `&&` is never reached here.
-            if (ch === ";" || ch === "|" || ch === "&") {
-                segments.push(current.trim());
-                current = "";
-                continue;
-            }
-        }
-        tracker.feed(ch);
-        current += ch;
-    }
-    // Bail on unbalanced quotes
-    if (tracker.state !== "NORMAL" || tracker.escaped) {
-        return null;
-    }
-    segments.push(current.trim());
-    return segments.filter((s) => s.length > 0);
-}
-/**
- * Identify the install form (if any) of a single top-level segment by its
- * leading token. Returns the matched package manager + the raw remaining
- * tokens (after the install verb) when a form is found.
- *
- * Leading-token rule — ONLY these forms are recognized:
- *   pip install …
- *   pip3 install …
- *   python -m pip install …
- *   python3 -m pip install …
- *   npm install … | npm i … | npm add …
- *   pnpm install … | pnpm add …
- *   yarn add …
- *
- * Quoted strings, command substitution, heredocs, and `npx`/`pwsh -c`
- * fall through to the `null` branch.
- */
-function parseInstallSegment(segment) {
-    // Whitespace-tokenize the segment. We deliberately do NOT re-tokenize
-    // with quote-awareness here — the leading-token rule only inspects the
-    // first whitespace-delimited token, and shell quoting at this layer is
-    // already consistent (parent splitTopLevelSegments left us a balanced
-    // segment). This is the design's "no recursive descent" position.
-    const tokens = segment.split(/\s+/).filter((t) => t.length > 0);
-    if (tokens.length === 0)
-        return null;
-    const lead = tokens[0];
-    if (lead === "pip" || lead === "pip3") {
-        if (tokens[1] !== "install")
-            return null;
-        return { packageManager: "pip", rawPackages: tokens.slice(2) };
-    }
-    if (lead === "python" || lead === "python3") {
-        // python -m pip install …
-        if (tokens[1] !== "-m" || tokens[2] !== "pip" || tokens[3] !== "install")
-            return null;
-        return { packageManager: "pip", rawPackages: tokens.slice(4) };
-    }
-    if (lead === "npm") {
-        const verb = tokens[1];
-        if (verb !== "install" && verb !== "i" && verb !== "add")
-            return null;
-        return { packageManager: "npm", rawPackages: tokens.slice(2) };
-    }
-    if (lead === "pnpm") {
-        const verb = tokens[1];
-        if (verb !== "install" && verb !== "add")
-            return null;
-        return { packageManager: "pnpm", rawPackages: tokens.slice(2) };
-    }
-    if (lead === "yarn") {
-        if (tokens[1] !== "add")
-            return null;
-        return { packageManager: "yarn", rawPackages: tokens.slice(2) };
-    }
-    return null;
-}
-/**
- * Classify one raw token from the install args:
- * - Returns `null` if it's a flag (starts with `-`).
- * - Returns `null` if it's URL/VCS/local-path/file spec.
- * - Returns the package name with version stripped for unscoped names.
- * - Preserves `@scope/name` and strips `@version` only at the SECOND `@`.
- */
-function classifyPackageToken(token, ecosystem) {
-    if (token.startsWith("-"))
-        return null; // flag — skip
-    // URL / VCS / local-path / file spec rejection
-    if (token.includes("://") ||
-        token.startsWith("git+") ||
-        token.startsWith("file:") ||
-        token.startsWith("./") ||
-        token.startsWith("../") ||
-        token.endsWith(".tar.gz") ||
-        token.endsWith(".whl") ||
-        token.endsWith(".zip")) {
-        return null;
-    }
-    // Scoped npm preservation: @scope/name or @scope/name@1.2.3
-    if (ecosystem === "node" && token.startsWith("@")) {
-        const slashIdx = token.indexOf("/");
-        if (slashIdx <= 0)
-            return null; // malformed @scope without name
-        const afterSlash = token.slice(slashIdx + 1);
-        const versionAt = afterSlash.indexOf("@");
-        const namePart = versionAt >= 0
-            ? afterSlash.slice(0, versionAt)
-            : afterSlash;
-        if (namePart.length === 0)
-            return null;
-        return token.slice(0, slashIdx + 1) + namePart; // "@scope/name"
-    }
-    // Unscoped: strip version specifiers from the FIRST occurrence of
-    // any of `==`, `>=`, `<=`, `<`, `>`, `!=`, `~=`, or `@`.
-    const versionRegex = /(==|>=|<=|!=|~=|<|>|@)/;
-    const match = token.search(versionRegex);
-    const namePart = match >= 0 ? token.slice(0, match) : token;
-    if (namePart.length === 0)
-        return null;
-    return namePart;
-}
-/** PEP 503 strict normalization: lowercase + collapse `-`/`_`/`.` runs to single `-`. */
-function normalizePythonName(name) {
-    return name.toLowerCase().replace(/[-_.]+/g, "-");
-}
-/** npm: lowercase only; `@scope/name` preserved exactly. */
-function normalizeNpmName(name) {
-    return name.toLowerCase();
-}
-/**
- * SHA-256 of `${pm}:${sortedPackages.join(",")}` truncated to 16 hex chars.
- * Stable, order-insensitive, distinct for distinct PMs/packages.
- * Mirrors `file-state-tracker.ts:160-163` crypto pattern + the
- * `SYSTEM_PROMPT_HASH_LENGTH = 16` truncation convention from
- * `packages/agent/src/context-engine/constants.ts:163`.
- */
-function buildCommandDigest(pm, packages) {
-    const sorted = [...packages].sort();
-    return createHash("sha256")
-        .update(`${pm}:${sorted.join(",")}`)
-        .digest("hex")
-        .slice(0, 16);
-}
-/**
- * Build per-call alias maps from the port's runtime view. NEVER memoize
- * across calls — avoids the skill-visibility race.
- *
- * Two SEPARATE maps keyed by ecosystem to avoid cross-ecosystem aliasing
- * collisions when an operator declares `replacesPackages: ["foo_bar"]`
- * (Python normalizes to `foo-bar`; npm preserves `foo_bar`). The parser
- * picks the appropriate map based on detected `packageManager`.
- */
-function buildPackageAliasMap(port) {
-    const pythonAliases = new Map();
-    const npmAliases = new Map();
-    // 1. MCP operator hints (tooling.mcp.capabilityHints[*].replacesPackages)
-    for (const server of port.getConnectedMcpServers()) {
-        const hint = port.getMcpServerHint(server);
-        if (!hint)
-            continue;
-        for (const pkg of hint.replacesPackages) {
-            const overlap = {
-                packageName: pkg.toLowerCase(),
-                sourceType: "mcp",
-                sourceName: server,
-                cluster: hint.cluster,
-                reason: "mcp-operator-alias",
-            };
-            const pyKey = normalizePythonName(pkg);
-            const npmKey = normalizeNpmName(pkg);
-            if (!pythonAliases.has(pyKey)) {
-                pythonAliases.set(pyKey, { ...overlap, packageName: pyKey });
-            }
-            if (!npmAliases.has(npmKey)) {
-                npmAliases.set(npmKey, { ...overlap, packageName: npmKey });
-            }
-        }
-    }
-    // 2. Skill aliases (operator hints + comis.capability — both pre-merged
-    //    by port.getPromptSkillCapabilities()).
-    //    Visibility filter (allowed/denied/eligibility/disableModelInvocation)
-    //    is already applied at the port level — no re-filter here.
-    for (const skill of port.getPromptSkillCapabilities()) {
-        // Discriminate operator-alias vs comis-alias: if port.getSkillHint
-        // returns truthy for this skill, the operator hint is the source.
-        const operatorHint = port.getSkillHint(skill.name, skill.skillKey);
-        const reason = operatorHint
-            ? "skill-operator-alias"
-            : "skill-comis-alias";
-        for (const pkg of skill.replacesPackages) {
-            const overlap = {
-                packageName: pkg.toLowerCase(),
-                sourceType: "skill",
-                sourceName: skill.name,
-                cluster: skill.cluster,
-                reason,
-            };
-            const pyKey = normalizePythonName(pkg);
-            const npmKey = normalizeNpmName(pkg);
-            // first-source-wins precedence: MCP entries already in the map are not overwritten
-            if (!pythonAliases.has(pyKey)) {
-                pythonAliases.set(pyKey, { ...overlap, packageName: pyKey });
-            }
-            if (!npmAliases.has(npmKey)) {
-                npmAliases.set(npmKey, { ...overlap, packageName: npmKey });
-            }
-        }
-    }
-    return { pythonAliases, npmAliases };
-}