@loucompanion/forge-bridge 0.1.1-dev.242bb53ef13f → 0.1.1-dev.32d4dd5874ee

package/dist/session/phase-completion.js

@@ -0,0 +1,737 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const toolServerName = "forge";
+const phaseFiles = {
+    implementation: {
+        jsonFileName: "implementation.completeness.json",
+        reportFileName: "implementation.report.md"
+    },
+    self_review: {
+        jsonFileName: "self-review.report.json",
+        reportFileName: "self-review.summary.md"
+    },
+    validation: {
+        jsonFileName: "validation.verdict.json",
+        reportFileName: "validation.report.md"
+    }
+};
+export function completionPhaseFromDispatch(dispatch) {
+    return normalizeCompletionPhase(dispatch.cycleRun.phase || dispatch.execution.lane || dispatch.execution.role);
+}
+export function normalizeCompletionPhase(value) {
+    const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
+    if (normalized === "self_review" || normalized === "selfreview" || normalized === "review") {
+        return "self_review";
+    }
+    if (normalized === "validate" || normalized === "validation") {
+        return "validation";
+    }
+    return "implementation";
+}
+export function completionToolNamesForPhase(phase) {
+    const base = phase === "implementation"
+        ? "complete_implementation"
+        : phase === "self_review"
+            ? "complete_self_review"
+            : "complete_validation";
+    return [`forge.${base}`, base];
+}
+export function expectedCompletionToolName(phase) {
+    return completionToolNamesForPhase(phase)[0];
+}
+export function artifactRootFor(worktreePath, workItemId) {
+    return path.join(worktreePath, ".forge", "work-items", safePathSegment(workItemId, "work item id"), "artifacts");
+}
+export function completionArtifactJsonPath(worktreePath, workItemId, phase) {
+    return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].jsonFileName);
+}
+export function completionArtifactReportPath(worktreePath, workItemId, phase) {
+    return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].reportFileName);
+}
+export async function prepareCompletionToolRuntime(options) {
+    const phase = options.phase ?? completionPhaseFromDispatch(options.dispatch);
+    const worktreePath = path.resolve(options.worktree.worktreePath);
+    const workItemId = options.dispatch.workItem.id;
+    const mcpArgs = buildCompletionToolServerArgs({
+        worktreePath,
+        workItemId,
+        phase,
+        producedBy: `${options.dispatch.execution.provider}-cli`
+    });
+    const runtime = {
+        serverName: toolServerName,
+        command: process.execPath,
+        args: [forgeBridgeCliBinPath(), ...mcpArgs],
+        env: {},
+        cleanup: async () => undefined
+    };
+    if (options.dispatch.execution.provider.trim().toLowerCase() !== "cursor") {
+        return runtime;
+    }
+    return await prepareCursorCompletionToolRuntime(worktreePath, runtime);
+}
+export function buildCompletionToolServerArgs(config) {
+    return [
+        "mcp",
+        "--worktree",
+        path.resolve(config.worktreePath),
+        "--work-item-id",
+        config.workItemId,
+        "--phase",
+        config.phase,
+        "--produced-by",
+        config.producedBy ?? "forge-completion-tool"
+    ];
+}
+export function codexMcpConfigArgs(runtime) {
+    const prefix = `mcp_servers.${runtime.serverName}`;
+    const args = [
+        "-c",
+        `${prefix}.command=${tomlString(runtime.command)}`,
+        "-c",
+        `${prefix}.args=${tomlStringArray(runtime.args)}`
+    ];
+    for (const [key, value] of Object.entries(runtime.env)) {
+        args.push("-c", `${prefix}.env.${key}=${tomlString(value)}`);
+    }
+    return args;
+}
+export function cursorMcpServerConfig(runtime) {
+    return {
+        command: runtime.command,
+        args: [...runtime.args],
+        env: runtime.env
+    };
+}
+export function completionPromptForPhase(phase) {
+    const toolName = expectedCompletionToolName(phase);
+    const alias = completionToolNamesForPhase(phase).find((name) => name !== toolName);
+    const artifactName = phaseFiles[phase].jsonFileName;
+    return `Forge completion tools are available through the MCP server named \`${toolServerName}\`.
+Do not write phase artifacts by hand. When the phase is complete, call \`${toolName}(...)\`${alias ? ` (or \`${alias}\` if your client shows unqualified MCP tool names)` : ""} with the required evidence payload.
+That tool writes \`.forge/work-items/{workItemId}/artifacts/${artifactName}\` and returns the artifact reference that Forge will mirror through the existing phase-artifact pipeline.
+If the work cannot pass, call the same tool with a non-pass status and explicit blockers instead of reporting completion in prose only.`;
+}
+export async function writeCompletionArtifact(config, toolName, input) {
+    const phase = phaseFromToolName(toolName);
+    if (phase !== config.phase) {
+        throw new Error(`Tool ${toolName} is not allowed for phase ${config.phase}.`);
+    }
+    const payload = asRecord(input, "completion payload");
+    validatePayloadShape(phase, payload);
+    validateOptionalWorkItemId(payload, config.workItemId);
+    const producedBy = optionalString(payload, "produced_by")
+        ?? optionalString(payload, "producedBy")
+        ?? config.producedBy
+        ?? "forge-completion-tool";
+    const status = requiredString(payload, "status").trim().toLowerCase();
+    const artifactWithoutHash = normalizeArtifactPayload(payload, {
+        phase,
+        workItemId: config.workItemId,
+        producedBy,
+        status
+    });
+    const contentHash = sha256(stableStringify(artifactWithoutHash));
+    const artifact = {
+        ...artifactWithoutHash,
+        content_hash: contentHash
+    };
+    const artifactJson = `${JSON.stringify(artifact, null, 2)}\n`;
+    const report = reportMarkdown(payload, phase, status, producedBy, contentHash);
+    const artifactPath = completionArtifactJsonPath(config.worktreePath, config.workItemId, phase);
+    const reportPath = completionArtifactReportPath(config.worktreePath, config.workItemId, phase);
+    await fs.mkdir(path.dirname(artifactPath), { recursive: true });
+    await writeFileAtomic(artifactPath, artifactJson);
+    await writeFileAtomic(reportPath, report);
+    return {
+        phase,
+        workItemId: config.workItemId,
+        repoPath: path.resolve(config.worktreePath),
+        path: artifactPath,
+        reportPath,
+        contentHash,
+        status,
+        producedBy
+    };
+}
+export async function readCompletionArtifact(worktreePath, workItemId, phase) {
+    const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase);
+    const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase);
+    const verdictJson = await readOptionalFile(artifactPath);
+    if (verdictJson === null) {
+        return null;
+    }
+    const parsed = parseJsonObject(verdictJson, artifactPath);
+    const report = await readOptionalFile(reportPath) ?? fallbackReport(parsed, phase, artifactPath);
+    return {
+        repoPath: path.resolve(worktreePath),
+        path: artifactPath,
+        verdictJson,
+        report,
+        producedBy: optionalString(parsed, "produced_by") ?? optionalString(parsed, "producedBy") ?? "forge-completion-tool",
+        status: optionalString(parsed, "status") ?? "unknown",
+        phase
+    };
+}
+export async function runCompletionMcpServer(config) {
+    process.stdin.setEncoding("utf8");
+    let buffer = "";
+    for await (const chunk of process.stdin) {
+        buffer += chunk;
+        let newlineIndex = buffer.indexOf("\n");
+        while (newlineIndex >= 0) {
+            const rawLine = buffer.slice(0, newlineIndex).trim();
+            buffer = buffer.slice(newlineIndex + 1);
+            if (rawLine.length > 0) {
+                await handleJsonRpcLine(config, rawLine);
+            }
+            newlineIndex = buffer.indexOf("\n");
+        }
+    }
+    const trailing = buffer.trim();
+    if (trailing.length > 0) {
+        await handleJsonRpcLine(config, trailing);
+    }
+}
+export function parseCompletionMcpArgs(argv) {
+    let worktreePath = null;
+    let workItemId = null;
+    let phase = "implementation";
+    let producedBy;
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--worktree") {
+            worktreePath = argv[++index] ?? null;
+        }
+        else if (arg === "--work-item-id") {
+            workItemId = argv[++index] ?? null;
+        }
+        else if (arg === "--phase") {
+            const rawPhase = argv[++index];
+            const parsedPhase = parseStrictCompletionPhase(rawPhase);
+            if (!parsedPhase) {
+                return { ok: false, error: "mcp --phase must be one of: implementation, self-review, validation." };
+            }
+            phase = parsedPhase;
+        }
+        else if (arg === "--produced-by") {
+            producedBy = argv[++index] ?? undefined;
+        }
+        else {
+            return { ok: false, error: `Unknown mcp argument: ${arg}` };
+        }
+    }
+    if (!worktreePath?.trim() || !workItemId?.trim()) {
+        return { ok: false, error: "mcp requires --worktree and --work-item-id." };
+    }
+    return {
+        ok: true,
+        config: {
+            worktreePath: path.resolve(worktreePath),
+            workItemId,
+            phase,
+            producedBy
+        }
+    };
+}
+async function prepareCursorCompletionToolRuntime(worktreePath, runtime) {
+    const cursorDir = path.join(worktreePath, ".cursor");
+    const configPath = path.join(cursorDir, "mcp.json");
+    const original = await fs.readFile(configPath, "utf8").then((content) => ({ existed: true, content }), () => ({ existed: false, content: "" }));
+    const existing = original.existed ? parseOptionalJsonObject(original.content, configPath) : {};
+    const servers = asMutableRecord(existing.mcpServers);
+    servers[runtime.serverName] = cursorMcpServerConfig(runtime);
+    const next = {
+        ...existing,
+        mcpServers: servers
+    };
+    await fs.mkdir(cursorDir, { recursive: true });
+    await writeFileAtomic(configPath, `${JSON.stringify(next, null, 2)}\n`);
+    return {
+        ...runtime,
+        cursorMcpConfigPath: configPath,
+        cleanup: async () => {
+            if (original.existed) {
+                await writeFileAtomic(configPath, original.content);
+            }
+            else {
+                await fs.rm(configPath, { force: true });
+                await fs.rmdir(cursorDir).catch(() => undefined);
+            }
+        }
+    };
+}
+async function handleJsonRpcLine(config, rawLine) {
+    let message;
+    try {
+        message = JSON.parse(rawLine);
+    }
+    catch (error) {
+        writeJsonRpc({ jsonrpc: "2.0", id: null, error: rpcError(-32700, errorMessage(error)) });
+        return;
+    }
+    const request = asJsonRpcMessage(message);
+    if (!request) {
+        writeJsonRpc({ jsonrpc: "2.0", id: null, error: rpcError(-32600, "Invalid JSON-RPC message.") });
+        return;
+    }
+    if (request.id === undefined) {
+        return;
+    }
+    try {
+        const result = await handleJsonRpcRequest(config, request.method, request.params);
+        writeJsonRpc({ jsonrpc: "2.0", id: request.id, result });
+    }
+    catch (error) {
+        writeJsonRpc({ jsonrpc: "2.0", id: request.id, error: rpcError(-32000, errorMessage(error)) });
+    }
+}
+async function handleJsonRpcRequest(config, method, params) {
+    if (method === "initialize") {
+        const initializeParams = params && typeof params === "object" && !Array.isArray(params)
+            ? params
+            : {};
+        return {
+            protocolVersion: typeof initializeParams.protocolVersion === "string" ? initializeParams.protocolVersion : "2025-06-18",
+            capabilities: {
+                tools: {}
+            },
+            serverInfo: {
+                name: "forge-completion-tools",
+                version: "0.1.0"
+            },
+            instructions: completionPromptForPhase(config.phase)
+        };
+    }
+    if (method === "ping") {
+        return {};
+    }
+    if (method === "tools/list") {
+        return {
+            tools: completionToolNamesForPhase(config.phase).map((name) => toolDefinition(name, config.phase))
+        };
+    }
+    if (method === "tools/call") {
+        const call = asRecord(params, "tools/call params");
+        const name = requiredString(call, "name");
+        const args = call.arguments ?? {};
+        const reference = await writeCompletionArtifact(config, name, args);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Forge recorded ${reference.phase} completion artifact ${path.relative(reference.repoPath, reference.path)} (${reference.status}, ${reference.contentHash}).`
+                }
+            ],
+            structuredContent: reference
+        };
+    }
+    throw new Error(`Unsupported MCP method: ${method}`);
+}
+function toolDefinition(name, phase) {
+    return {
+        name,
+        description: toolDescription(phase),
+        inputSchema: toolInputSchema(phase)
+    };
+}
+function toolDescription(phase) {
+    if (phase === "implementation") {
+        return "Complete Forge implementation by writing implementation.completeness.json with scoped changed-file, verification, acceptance-criteria, gap, and next-phase evidence.";
+    }
+    if (phase === "self_review") {
+        return "Complete Forge self-review by writing self-review.report.json with diff review, findings, security, edge-case, design, deterministic-comparison, fixes, and remaining-risk evidence.";
+    }
+    return "Complete Forge validation by writing validation.verdict.json with command, build/test/lint/design, drift, acceptance-criteria, and ready-for-dev-test evidence.";
+}
+function toolInputSchema(phase) {
+    const base = {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+            status: { type: "string", enum: ["pass", "blocked", "fail", "failed"] },
+            summary: { type: "string" },
+            report_markdown: { type: "string" },
+            blockers: { type: "array" }
+        },
+        required: ["status", "summary"]
+    };
+    if (phase === "implementation") {
+        return {
+            ...base,
+            properties: {
+                ...base.properties,
+                plan: { type: "array" },
+                changed_files: { type: "array" },
+                tests_added_or_updated: { type: "array" },
+                docs_added_or_updated: { type: "array" },
+                verification: { type: "array" },
+                acceptance_criteria: { type: "array" },
+                known_gaps: { type: "array" },
+                next_phase_context: {}
+            },
+            required: ["status", "summary"]
+        };
+    }
+    if (phase === "self_review") {
+        return {
+            ...base,
+            properties: {
+                ...base.properties,
+                reviewed_diff: { type: "boolean" },
+                findings: { type: "array" },
+                security_review: { type: "object" },
+                edge_case_review: { type: "object" },
+                design_review: { type: "object" },
+                deterministic_comparison: { type: "object" },
+                fixes_applied: { type: "array" },
+                remaining_risks: { type: "array" }
+            },
+            required: ["status", "summary"]
+        };
+    }
+    return {
+        ...base,
+        properties: {
+            ...base.properties,
+            commands: { type: "array" },
+            acceptance_criteria: { type: "array" },
+            build_status: { type: "string" },
+            test_status: { type: "string" },
+            lint_status: { type: "string" },
+            design_status: { type: "string" },
+            drift_checks: { type: "array" },
+            ready_for_dev_test: { type: "boolean" }
+        },
+        required: ["status", "summary"]
+    };
+}
+function validatePayloadShape(phase, payload) {
+    const status = requiredString(payload, "status").trim().toLowerCase();
+    if (!status) {
+        throw new Error("status is required.");
+    }
+    const pass = status === "pass";
+    requireField(payload, "summary");
+    if (!pass) {
+        requireNonPassEvidence(payload);
+        return;
+    }
+    if (phase === "implementation") {
+        requireArray(payload, "plan");
+        requireArray(payload, "changed_files");
+        requireArray(payload, "tests_added_or_updated");
+        requireArray(payload, "docs_added_or_updated");
+        requireArray(payload, "acceptance_criteria");
+        requireArray(payload, "known_gaps");
+        requireField(payload, "next_phase_context");
+        requireImplementationEvidence(payload);
+        requireSatisfiedAcceptanceCriteria(payload);
+        return;
+    }
+    if (phase === "self_review") {
+        requireBoolean(payload, "reviewed_diff");
+        requireArray(payload, "findings");
+        requireObject(payload, "security_review");
+        requireObject(payload, "edge_case_review");
+        requireObject(payload, "design_review");
+        requireObject(payload, "deterministic_comparison");
+        requireArray(payload, "fixes_applied");
+        requireArray(payload, "remaining_risks");
+        return;
+    }
+    requireArray(payload, "commands");
+    requireArray(payload, "acceptance_criteria");
+    requireField(payload, "build_status");
+    requireField(payload, "test_status");
+    requireField(payload, "lint_status");
+    requireField(payload, "design_status");
+    requireArray(payload, "drift_checks");
+    requireBoolean(payload, "ready_for_dev_test");
+    if (payload.ready_for_dev_test !== true) {
+        throw new Error("validation pass requires ready_for_dev_test: true.");
+    }
+    requirePassingCommands(payload);
+    requireSatisfiedAcceptanceCriteria(payload);
+}
+function validateOptionalWorkItemId(payload, expectedWorkItemId) {
+    const actual = optionalString(payload, "work_item_id") ?? optionalString(payload, "workItemId");
+    if (actual && actual !== expectedWorkItemId) {
+        throw new Error(`completion payload work item ${actual} does not match dispatch work item ${expectedWorkItemId}.`);
+    }
+}
+function normalizeArtifactPayload(payload, defaults) {
+    const normalized = stripUndefined({ ...payload });
+    delete normalized.report_markdown;
+    delete normalized.content_hash;
+    delete normalized.contentHash;
+    normalized.schema_version = numberOrDefault(normalized.schema_version, 1);
+    normalized.phase = defaults.phase;
+    normalized.work_item_id = defaults.workItemId;
+    normalized.status = defaults.status;
+    normalized.produced_by = defaults.producedBy;
+    return normalized;
+}
+function reportMarkdown(payload, phase, status, producedBy, contentHash) {
+    const explicit = optionalString(payload, "report_markdown");
+    if (explicit) {
+        return explicit.endsWith("\n") ? explicit : `${explicit}\n`;
+    }
+    const summary = optionalString(payload, "summary") ?? "No summary provided.";
+    return `# Forge ${phase.replace(/_/g, " ")} completion
+
+Status: ${status}
+Produced by: ${producedBy}
+Content hash: ${contentHash}
+
+## Summary
+
+${summary}
+`;
+}
+function parseStrictCompletionPhase(value) {
+    const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
+    if (normalized === "implementation" || normalized === "implement" || normalized === "develop") {
+        return "implementation";
+    }
+    if (normalized === "self_review" || normalized === "selfreview" || normalized === "review") {
+        return "self_review";
+    }
+    if (normalized === "validate" || normalized === "validation") {
+        return "validation";
+    }
+    return null;
+}
+function phaseFromToolName(toolName) {
+    const normalized = toolName.trim().toLowerCase();
+    if (normalized === "forge.complete_implementation" || normalized === "complete_implementation") {
+        return "implementation";
+    }
+    if (normalized === "forge.complete_self_review" || normalized === "complete_self_review") {
+        return "self_review";
+    }
+    if (normalized === "forge.complete_validation" || normalized === "complete_validation") {
+        return "validation";
+    }
+    throw new Error(`Unknown Forge completion tool: ${toolName}`);
+}
+function requireField(payload, key) {
+    if (payload[key] === undefined || payload[key] === null || (typeof payload[key] === "string" && payload[key].trim().length === 0)) {
+        throw new Error(`${key} is required.`);
+    }
+}
+function requireNonPassEvidence(payload) {
+    const evidenceKeys = ["blockers", "known_gaps", "findings", "remaining_risks", "commands", "failures"];
+    const hasEvidence = evidenceKeys.some((key) => {
+        const value = payload[key];
+        if (typeof value === "string") {
+            return value.trim().length > 0;
+        }
+        if (Array.isArray(value)) {
+            return value.length > 0;
+        }
+        return Boolean(value && typeof value === "object");
+    });
+    if (!hasEvidence) {
+        throw new Error("non-pass completion requires explicit blockers, findings, failures, or known gaps.");
+    }
+}
+function requireImplementationEvidence(payload) {
+    const knownGaps = payload.known_gaps;
+    const hasKnownGap = Array.isArray(knownGaps) && knownGaps.length > 0;
+    for (const key of ["changed_files", "tests_added_or_updated", "docs_added_or_updated"]) {
+        const value = payload[key];
+        if (Array.isArray(value) && value.length === 0 && !hasKnownGap) {
+            throw new Error(`${key} is empty; known_gaps must explain why.`);
+        }
+    }
+}
+function requirePassingCommands(payload) {
+    const commands = payload.commands;
+    if (!Array.isArray(commands)) {
+        return;
+    }
+    if (commands.length === 0) {
+        throw new Error("commands must include at least one deterministic validation command.");
+    }
+    for (const [index, command] of commands.entries()) {
+        if (!command || typeof command !== "object" || Array.isArray(command)) {
+            throw new Error(`commands[${index}] must be an object.`);
+        }
+        const record = command;
+        if (typeof record.command !== "string" || record.command.trim().length === 0) {
+            throw new Error(`commands[${index}].command must be a non-empty string.`);
+        }
+        if (typeof record.summary !== "string" || record.summary.trim().length === 0) {
+            throw new Error(`commands[${index}].summary must be a non-empty string.`);
+        }
+        if (typeof record.exit_code !== "number" || !Number.isFinite(record.exit_code)) {
+            throw new Error(`commands[${index}].exit_code must be a finite number.`);
+        }
+        if (record.exit_code !== 0) {
+            throw new Error(`commands[${index}].exit_code must be 0 when status is pass.`);
+        }
+        const status = typeof record.status === "string" ? record.status.trim().toLowerCase() : "";
+        if (status !== "pass") {
+            throw new Error(`commands[${index}].status must be pass.`);
+        }
+    }
+}
+function requireArray(payload, key) {
+    if (!Array.isArray(payload[key])) {
+        throw new Error(`${key} must be an array.`);
+    }
+}
+function requireObject(payload, key) {
+    const value = payload[key];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${key} must be an object.`);
+    }
+}
+function requireBoolean(payload, key) {
+    if (typeof payload[key] !== "boolean") {
+        throw new Error(`${key} must be a boolean.`);
+    }
+}
+function requireSatisfiedAcceptanceCriteria(payload) {
+    const criteria = payload.acceptance_criteria;
+    if (!Array.isArray(criteria)) {
+        return;
+    }
+    for (const [index, criterion] of criteria.entries()) {
+        if (!criterion || typeof criterion !== "object" || Array.isArray(criterion)) {
+            throw new Error(`acceptance_criteria[${index}] must be an object.`);
+        }
+        const record = criterion;
+        const status = optionalString(record, "status")?.toLowerCase();
+        const evidence = optionalString(record, "evidence");
+        if (status !== "satisfied" || !evidence) {
+            throw new Error(`acceptance_criteria[${index}] must be satisfied with evidence for status pass.`);
+        }
+    }
+}
+function fallbackReport(parsed, phase, artifactPath) {
+    return `# Forge ${phase.replace(/_/g, " ")} completion
+
+Artifact: ${artifactPath}
+Status: ${optionalString(parsed, "status") ?? "unknown"}
+`;
+}
+function parseJsonObject(content, label) {
+    try {
+        return asRecord(JSON.parse(content), label);
+    }
+    catch (error) {
+        throw new Error(`${label} is not valid JSON: ${errorMessage(error)}`);
+    }
+}
+function parseOptionalJsonObject(content, label) {
+    if (!content.trim()) {
+        return {};
+    }
+    return parseJsonObject(content, label);
+}
+function asRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+}
+function asMutableRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? { ...value }
+        : {};
+}
+function requiredString(source, key) {
+    const value = source[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${key} must be a non-empty string.`);
+    }
+    return value;
+}
+function optionalString(source, key) {
+    const value = source[key];
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+function numberOrDefault(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function stripUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function safePathSegment(value, label) {
+    if (!value.trim() || value.includes("/") || value.includes("\\") || value === "." || value === "..") {
+        throw new Error(`${label} is not a safe path segment.`);
+    }
+    return value;
+}
+async function readOptionalFile(filePath) {
+    return await fs.readFile(filePath, "utf8").catch((error) => {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    });
+}
+async function writeFileAtomic(filePath, content) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    await fs.writeFile(tempPath, content, "utf8");
+    await fs.rename(tempPath, filePath);
+}
+function stableStringify(value) {
+    return JSON.stringify(sortJson(value));
+}
+function sortJson(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortJson);
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, entry]) => [key, sortJson(entry)]));
+    }
+    return value;
+}
+function sha256(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+function forgeBridgeCliBinPath() {
+    return fileURLToPath(new URL("../cli/bin.js", import.meta.url));
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function tomlStringArray(values) {
+    return `[${values.map(tomlString).join(", ")}]`;
+}
+function writeJsonRpc(message) {
+    process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+function rpcError(code, message) {
+    return { code, message };
+}
+function asJsonRpcMessage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const message = value;
+    if (message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+        return null;
+    }
+    const id = message.id;
+    return {
+        id: typeof id === "string" || typeof id === "number" || id === null ? id : undefined,
+        method: message.method,
+        params: message.params
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}