@cueai/omni-reader-mcp 1.5.4 → 1.6.0

package/dist/operation-manager.js

@@ -4,8 +4,8 @@ import { OmniBridgeError } from "./errors.js";
 import { LEGACY_RECOVERY_FAILURE_CODE } from "./operation-journal.js";
 import { openAllowedFile, } from "./path-security.js";
 import { NOOP_PROGRESS } from "./progress.js";
-import { normalizeRepresentation } from "./protocol.js";
-import { localResultToResultField } from "./result-contract.js";
+import { normalizeRepresentation, } from "./protocol.js";
+import { LOCAL_ARTIFACT_RETENTION_WARNING, createFlatLocalResultCache, localResultToResultField, presentRetainedResult, } from "./result-contract.js";
 const TERMINAL_STATES = new Set([
     "COMPLETED",
     "FAILED",
@@ -217,30 +217,52 @@ function resultFromRecord(record) {
 export class OperationManager {
     #journal;
     #driver;
+    #presentResult;
     #now;
     #sleep;
     #submissions = new Map();
+    #submissionDelivery = new Map();
     #executions = new Map();
     #results = new Map();
     constructor(options) {
         this.#journal = options.journal;
         this.#driver = options.driver;
+        this.#presentResult = options.presentResult ?? (async (_record, result) => result);
         this.#now = options.now ?? Date.now;
         this.#sleep = options.sleep ?? defaultSleep;
     }
+    async #strengthenResultDelivery(record, requested) {
+        if (requested === "auto" || record.resultDeliveryEffective === "artifact") {
+            return record;
+        }
+        if (record.requestIdentityHmac === null
+            && record.errorCode === LEGACY_RECOVERY_FAILURE_CODE) {
+            return record;
+        }
+        return this.#journal.strengthenResultDelivery(record.clientRequestId, requested);
+    }
     async submit(input) {
         const requestHash = operationRequestHash(input);
+        const requestedDelivery = input.resultDelivery ?? "auto";
+        if (requestedDelivery === "artifact"
+            || this.#submissionDelivery.get(requestHash) === undefined) {
+            this.#submissionDelivery.set(requestHash, requestedDelivery);
+        }
         const active = this.#submissions.get(requestHash);
-        if (active !== undefined)
-            return active;
+        if (active !== undefined) {
+            const record = await active;
+            return this.#strengthenResultDelivery(record, requestedDelivery);
+        }
         const pending = this.#submit(input);
         this.#submissions.set(requestHash, pending);
         try {
-            return await pending;
+            const record = await pending;
+            return await this.#strengthenResultDelivery(record, this.#submissionDelivery.get(requestHash) ?? requestedDelivery);
         }
         finally {
             if (this.#submissions.get(requestHash) === pending) {
                 this.#submissions.delete(requestHash);
+                this.#submissionDelivery.delete(requestHash);
             }
         }
     }
@@ -282,7 +304,7 @@ export class OperationManager {
                 effectiveInput = { ...input, clientRequestId: matching.clientRequestId };
             }
             else {
-                record = await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation);
+                record = await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation, input.resultDelivery ?? "auto");
             }
         }
         else if (record.requestIdentityHmac === null) {
@@ -291,18 +313,26 @@ export class OperationManager {
             // recovery failure. It can never be resumed as grounded/layout.
             const migrated = await this.#journal.migrateLegacyRecord(input.clientRequestId, identityJson, sourceLocator);
             record = migrated === null
-                ? await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation)
+                ? await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation, input.resultDelivery ?? "auto")
                 : migrated;
             if (TERMINAL_STATES.has(record.state))
                 return record;
         }
         else {
-            record = await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation);
+            record = await this.#journal.beginIntent(input.clientRequestId, identityJson, input.sourceKind, sourceLocator, representation, input.resultDelivery ?? "auto");
         }
+        record = await this.#strengthenResultDelivery(record, input.resultDelivery ?? "auto");
         const signal = effectiveInput.signal ?? new AbortController().signal;
         if (TERMINAL_STATES.has(record.state))
             return record;
         if (record.state !== "CREATED") {
+            if (record.sourceKind === "url"
+                && record.operationId !== null) {
+                // The remote server already owns this operation. A repeated parse call
+                // would create or attach to a second remote submission; callers must
+                // reuse the journaled operation and continue through status instead.
+                return record;
+            }
             if (record.operationId !== null && this.#executions.has(record.operationId)) {
                 return record;
             }
@@ -334,6 +364,14 @@ export class OperationManager {
             throw structured;
         }
     }
+    async #present(record, canonicalResult) {
+        if (canonicalResult.status === "processing")
+            return canonicalResult;
+        const latest = record.operationId === null
+            ? await this.#journal.loadByRequestId(record.clientRequestId)
+            : await this.#journal.loadByOperationId(record.operationId);
+        return this.#presentResult(latest ?? record, canonicalResult);
+    }
     async submitResult(input, foregroundBudgetMs = FOREGROUND_BUDGET_MS) {
         const startedAt = this.#now();
         let record = await this.submit(input);
@@ -341,19 +379,20 @@ export class OperationManager {
             ? undefined
             : this.#results.get(record.operationId);
         if (existingResult !== undefined)
-            return existingResult;
+            return this.#present(record, existingResult);
         const execution = record.operationId === null
             ? undefined
             : this.#executions.get(record.operationId);
         if (execution === undefined) {
-            return TERMINAL_STATES.has(record.state) && record.operationId !== null
-                ? this.statusResult(record.operationId, 0, input.signal)
-                : resultFromRecord(record);
+            if (TERMINAL_STATES.has(record.state) && record.operationId !== null) {
+                return this.statusResult(record.operationId, 0, input.signal);
+            }
+            return this.#present(record, resultFromRecord(record));
         }
         const remaining = Math.max(0, foregroundBudgetMs - (this.#now() - startedAt));
         if (remaining === 0) {
             record = await this.#applyUpdate(record, execution.handle.snapshot());
-            return resultFromRecord(record);
+            return this.#present(record, resultFromRecord(record));
         }
         const winner = await Promise.race([
             execution.settled.then((result) => ({ kind: "completed", result })),
@@ -361,76 +400,80 @@ export class OperationManager {
         ]);
         if (winner.kind === "completed") {
             return this.#now() - startedAt < foregroundBudgetMs
-                ? winner.result
-                : resultFromRecord(record);
+                ? this.#present(record, winner.result)
+                : this.#present(record, resultFromRecord(record));
         }
         const current = await this.#journal.loadByOperationId(record.operationId);
         if (current !== null && !TERMINAL_STATES.has(current.state)) {
             record = await this.#applyUpdate(current, execution.handle.snapshot());
         }
-        else if (current !== null) {
-            record = current;
-        }
-        return resultFromRecord(record);
+        return this.#present(record, resultFromRecord(record));
     }
     async statusResult(operationId, waitMs = 0, signal = new AbortController().signal) {
         const boundedWait = Math.min(STATUS_LONG_POLL_MAX_MS, Math.max(0, waitMs));
         let record = await this.#existingOperation(operationId);
         const cached = this.#results.get(operationId);
-        if (cached !== undefined && TERMINAL_STATES.has(record.state))
-            return cached;
+        if (cached !== undefined && TERMINAL_STATES.has(record.state)) {
+            return this.#present(record, cached);
+        }
         if (TERMINAL_STATES.has(record.state)) {
             const recovered = await this.#driver.result?.(record, signal);
             if (recovered !== undefined) {
                 this.#results.set(operationId, recovered);
-                return recovered;
+                return this.#present(record, recovered);
             }
-            return resultFromRecord(record);
+            return this.#present(record, resultFromRecord(record));
         }
         if (record.resultExpiresAt !== null &&
             Date.parse(record.resultExpiresAt) <= this.#now()) {
             record = await this.#journal.transition(record.clientRequestId, record.state, "EXPIRED", { errorCode: "RESULT_EXPIRED" });
-            return resultFromRecord(record);
+            return this.#present(record, resultFromRecord(record));
         }
         let execution = this.#executions.get(operationId);
         if (execution === undefined) {
             record = await this.status(operationId, boundedWait, signal);
             const statusResult = this.#results.get(operationId);
             if (statusResult !== undefined && TERMINAL_STATES.has(record.state)) {
-                return statusResult;
+                return this.#present(record, statusResult);
             }
             execution = this.#executions.get(operationId);
-            if (execution === undefined)
-                return statusResult ?? resultFromRecord(record);
+            if (execution === undefined) {
+                return this.#present(record, statusResult ?? resultFromRecord(record));
+            }
         }
         if (!TERMINAL_STATES.has(record.state)) {
             record = await this.#applyUpdate(record, execution.handle.snapshot());
         }
-        if (boundedWait === 0)
-            return this.#results.get(operationId) ?? resultFromRecord(record);
+        if (boundedWait === 0) {
+            return this.#present(record, this.#results.get(operationId) ?? resultFromRecord(record));
+        }
         const winner = await Promise.race([
             execution.settled.then((value) => ({ kind: "completed", value })),
             this.#sleep(boundedWait).then(() => ({ kind: "timeout" })),
         ]);
         if (winner.kind === "completed")
-            return winner.value;
+            return this.#present(record, winner.value);
         const current = await this.#existingOperation(operationId);
         record = TERMINAL_STATES.has(current.state)
             ? current
             : await this.#applyUpdate(current, execution.handle.snapshot());
-        return this.#results.get(operationId) ?? resultFromRecord(record);
+        return this.#present(record, this.#results.get(operationId) ?? resultFromRecord(record));
     }
     async cancelResult(operationId, signal = new AbortController().signal) {
+        let record = await this.#existingOperation(operationId);
         const existing = this.#results.get(operationId);
-        if (existing !== undefined && existing.status !== "processing")
-            return existing;
+        if (existing !== undefined && existing.status !== "processing") {
+            return this.#present(record, existing);
+        }
         const execution = this.#executions.get(operationId);
         if (execution !== undefined) {
             await execution.handle.cancel();
-            return execution.settled;
+            const settled = await execution.settled;
+            record = await this.#existingOperation(operationId);
+            return this.#present(record, settled);
         }
-        const record = await this.cancel(operationId, signal);
-        return this.#results.get(operationId) ?? resultFromRecord(record);
+        record = await this.cancel(operationId, signal);
+        return this.#present(record, this.#results.get(operationId) ?? resultFromRecord(record));
     }
     async status(operationId, waitMs, signal = new AbortController().signal) {
         const record = await this.#existingOperation(operationId);
@@ -537,18 +580,10 @@ export class OperationManager {
     }
     #shouldReuseByRequestHash(record) {
         if (!TERMINAL_STATES.has(record.state)) {
-            // Local uploads may resume mid-flight (restart recovery). URL recovery
-            // is only valid BEFORE the remote operation exists (GRANT_PENDING — the
-            // retry reuses the same request identity and the server's idempotency
-            // key dedupes). Once a URL op is PROCESSING (operationId set), the
-            // server owns it and a fresh parse creates a NEW operation id — reusing
-            // the stale record pairs old op_id with the server's new one →
-            // "changed the operation identifier" → REMOTE_PROTOCOL_ERROR
-            // (dogfood 2026-08-06). Reuse URL non-terminal records only when no
-            // operation id has been issued yet.
-            if (record.sourceKind === "url") {
-                return record.operationId === null;
-            }
+            // Local uploads may resume mid-flight. URL request identities must also
+            // reuse the existing record: before an operation id exists, the retry
+            // keeps the same server idempotency key; after it exists, #submit returns
+            // the record without calling parse again and callers continue by status.
             return true;
         }
         if (record.state !== "COMPLETED" || record.operationId === null)
@@ -663,18 +698,34 @@ export async function hydrateInlineUrlResult(result, artifactStore) {
         ...start,
         resultDigest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
     });
-    return { ...result, result: localResultToResultField(retention.result()) };
+    const local = retention.result();
+    return {
+        ...result,
+        result: localResultToResultField(local),
+        local_result_cache: createFlatLocalResultCache({
+            resultId: local.resultId,
+            resultBytes: local.resultBytes,
+            expiresAt: local.expiresAt,
+        }),
+    };
 }
 // hydrateInlineUrlResult is a pure local-storage optimization on top of content the caller
 // already has in full -- a local-disk failure here (e.g. disk full, permission error) must never
-// turn an otherwise-successful URL parse into a failure. This wrapper swallows any hydration
-// error and falls back to the original, un-hydrated result: the caller still gets their content;
-// they just lose local read_result/read_outline re-read capability for that particular result.
+// turn an otherwise-successful URL parse into a failure. Preserve the delivered inline content
+// and expose one exact warning instead of silently advertising unavailable local actions.
 export async function hydrateInlineUrlResultSafely(result, artifactStore) {
     try {
         return await hydrateInlineUrlResult(result, artifactStore);
     }
     catch {
+        if ((result.status === "completed" || result.status === "cleanup_pending")
+            && result.result?.kind === "inline") {
+            const { local_result_cache: _unavailableCache, ...delivered } = result;
+            return {
+                ...delivered,
+                delivery_warning: LOCAL_ARTIFACT_RETENTION_WARNING,
+            };
+        }
         return result;
     }
 }
@@ -723,6 +774,13 @@ function remoteFailure(result) {
         ...(error.constraints === undefined ? {} : { constraints: error.constraints }),
     });
 }
+function retainedFlatResultId(result) {
+    if (result.status !== "completed" && result.status !== "cleanup_pending") {
+        return undefined;
+    }
+    const cache = result.local_result_cache;
+    return cache !== undefined && "result_id" in cache ? cache.result_id : undefined;
+}
 function remoteResultUpdate(result, expectedOperationId) {
     if (result.status === "failed")
         throw remoteFailure(result);
@@ -770,6 +828,9 @@ function remoteResultUpdate(result, expectedOperationId) {
                 processingCopy: "deleted",
                 temporaryData: "deleted",
                 deliveryResult: "deleted_after_ack",
+                ...(retainedFlatResultId(result) === undefined
+                    ? {}
+                    : { resultId: retainedFlatResultId(result) }),
             },
             result,
         };
@@ -793,6 +854,9 @@ function remoteResultUpdate(result, expectedOperationId) {
                 temporaryData: result.data_handling.temporary_data,
                 deliveryResult: "pending",
                 resultExpiresAt: result.cleanup_deadline,
+                ...(retainedFlatResultId(result) === undefined
+                    ? {}
+                    : { resultId: retainedFlatResultId(result) }),
             },
             result,
         };
@@ -890,6 +954,19 @@ function localResultValue(local) {
         next_cursor: local.nextCursor,
     };
 }
+function localResultCache(local) {
+    if (local.kind === "bundle") {
+        return {
+            expires_at: local.expiresAt,
+            discard_action: "discard_result",
+        };
+    }
+    return createFlatLocalResultCache({
+        resultId: local.resultId,
+        resultBytes: local.resultBytes,
+        expiresAt: local.expiresAt,
+    });
+}
 function completedLocalParse(local) {
     return {
         status: "completed",
@@ -902,12 +979,7 @@ function completedLocalParse(local) {
             original_source: "unchanged",
             remote_content_retained: false,
         },
-        ...(local.kind === "artifact" || local.kind === "bundle" ? {
-            local_result_cache: {
-                expires_at: local.expiresAt,
-                discard_action: "discard_result",
-            },
-        } : {}),
+        local_result_cache: localResultCache(local),
     };
 }
 function cleanupPendingParse(local, cleanupDeadline) {
@@ -922,6 +994,39 @@ function cleanupPendingParse(local, cleanupDeadline) {
             delivery_result: "pending",
             original_source: "unchanged",
         },
+        local_result_cache: localResultCache(local),
+    };
+}
+function withRecoveredRemoteResult(result, local) {
+    if (result.status !== "completed" && result.status !== "cleanup_pending") {
+        return result;
+    }
+    return {
+        ...result,
+        result: localResultValue(local),
+        local_result_cache: localResultCache(local),
+    };
+}
+function recoveredRemoteParse(record, local) {
+    if (record.operationId === null) {
+        throw managerError("OPERATION_ID_UNAVAILABLE", "The remote parse operation identifier is unavailable.");
+    }
+    if (record.state === "CLEANUP_PENDING") {
+        return {
+            status: "cleanup_pending",
+            operation_id: record.operationId,
+            result: localResultValue(local),
+            cleanup_deadline: record.resultExpiresAt ?? record.expiresAt ?? new Date(0).toISOString(),
+            data_handling: recordDataHandling(record),
+            local_result_cache: localResultCache(local),
+        };
+    }
+    return {
+        status: "completed",
+        operation_id: record.operationId,
+        result: localResultValue(local),
+        data_handling: recordDataHandling(record),
+        local_result_cache: localResultCache(local),
     };
 }
 function canceledParse(operationId, cleanupDeadline) {
@@ -1033,6 +1138,30 @@ export function createLocalParseOperationManager(options) {
         }
         throw managerError("JOURNAL_STATE_CONFLICT", "The operation changed repeatedly while saving a delivery checkpoint.", { operationCreated: true, retryable: true });
     }
+    async function recoverArtifactAccess(record, action) {
+        try {
+            return await action();
+        }
+        catch (error) {
+            const local = localFailure(error);
+            throw new OmniBridgeError({
+                code: local.code,
+                message: local.message,
+                failureScope: local.failureScope,
+                sourceKind: local.sourceKind,
+                userAction: local.userAction,
+                requestId: local.requestId,
+                operationCreated: local.operationCreated || record.operationId !== null,
+                fileUploaded: local.fileUploaded || record.fileUploaded,
+                parserStarted: local.parserStarted || record.parserStarted,
+                billed: local.billed || record.billed,
+                contentReleased: local.contentReleased || record.contentReleased,
+                retryable: local.retryable,
+                retryAfter: local.retryAfter,
+                constraints: local.constraints,
+            });
+        }
+    }
     // A retained logical bundle is reconstructed through its closed descriptor
     // and keeps the stored representation tuple; without the descriptor the
     // recovery fails safe instead of degrading the bundle to text.
@@ -1056,7 +1185,7 @@ export function createLocalParseOperationManager(options) {
                     contentReleased: record.contentReleased,
                 });
             }
-            const descriptor = await options.artifactStore.readBundleDescriptor(record.resultId);
+            const descriptor = await recoverArtifactAccess(record, () => options.artifactStore.readBundleDescriptor(record.resultId));
             if (descriptor === null || descriptor.kind !== "bundle") {
                 throw managerError("RESULT_NOT_AVAILABLE", "The retained local result bundle is unavailable.", {
                     operationCreated: true,
@@ -1068,11 +1197,11 @@ export function createLocalParseOperationManager(options) {
             }
             return descriptor;
         }
-        const preview = await options.artifactStore.read(record.resultId, undefined, 2_048);
+        const preview = await recoverArtifactAccess(record, () => options.artifactStore.read(record.resultId, undefined, 2_048));
         if (preview.resultBytes <= INLINE_RESULT_MAX_BYTES) {
             const recovered = preview.nextCursor === undefined
                 ? preview
-                : await options.artifactStore.read(record.resultId, undefined, INLINE_RESULT_MAX_BYTES);
+                : await recoverArtifactAccess(record, () => options.artifactStore.read(record.resultId, undefined, INLINE_RESULT_MAX_BYTES));
             if (recovered.nextCursor !== undefined) {
                 throw managerError("LOCAL_RESULT_INTEGRITY_FAILED", "The retained inline result was not fully readable.", {
                     operationCreated: true,
@@ -1101,6 +1230,16 @@ export function createLocalParseOperationManager(options) {
             ...(preview.nextCursor === undefined ? {} : { nextCursor: preview.nextCursor }),
         };
     }
+    async function preflightArtifactDelivery(input, recovery) {
+        const delivery = recovery?.resultDeliveryEffective ?? input.resultDelivery ?? "auto";
+        if (delivery !== "artifact")
+            return;
+        if (options.artifactStore.preflightWrite === undefined
+            || options.artifactStore.mintReadCursor === undefined) {
+            throw managerError("ARTIFACT_PREFLIGHT_FAILED", "The local result store cannot provide artifact delivery.");
+        }
+        await options.artifactStore.preflightWrite();
+    }
     async function startExecution(input, recovery) {
         // Recovery keeps the stored representation tuple exactly: status, download
         // (recoverLocalArtifact), and ACK all operate on the representation the
@@ -1136,6 +1275,7 @@ export function createLocalParseOperationManager(options) {
                 throw managerError("SOURCE_CHANGED_DURING_SUBMISSION", "The local source changed before the upload operation was created.", { retryable: true });
             }
             try {
+                await preflightArtifactDelivery(input, recovery);
                 // D2-D Task 14: the normalized detail reaches the grant boundary so
                 // CubeGrantClient selects the exact direct profile BEFORE constructing
                 // the v3 request and requires the v3 response tuple before any upload.
@@ -1492,6 +1632,7 @@ export function createLocalParseOperationManager(options) {
             assertSameRepresentation(input, recovery);
         }
         const context = remoteContext(input.context);
+        await preflightArtifactDelivery(input, recovery);
         const result = await options.remoteClient.parse(context.source, input.clientRequestId, input.signal ?? new AbortController().signal, representation.detail);
         const hydrated = await hydrateInlineUrlResultSafely(result, options.artifactStore);
         return remoteResultUpdate(hydrated, recovery?.operationId ?? undefined);
@@ -1507,9 +1648,30 @@ export function createLocalParseOperationManager(options) {
             if (record.operationId === null)
                 return undefined;
             if (record.sourceKind === "url") {
-                if (options.remoteClient === undefined)
-                    return undefined;
+                if (options.remoteClient === undefined) {
+                    if (record.resultId === null || record.state !== "CLEANUP_PENDING") {
+                        return undefined;
+                    }
+                    return {
+                        state: record.state,
+                        result: recoveredRemoteParse(record, await recoverLocalArtifact(record)),
+                    };
+                }
                 const result = await options.remoteClient.status(record.operationId, waitMs, signal);
+                if (record.resultId !== null && record.state === "CLEANUP_PENDING") {
+                    let local;
+                    try {
+                        local = await recoverLocalArtifact(record);
+                    }
+                    catch {
+                        // A missing or corrupt retained copy must not block authoritative
+                        // remote status recovery. Rehydrate the returned body when it is
+                        // available, preserving the existing safe warning behavior.
+                    }
+                    if (local !== undefined) {
+                        return remoteResultUpdate(withRecoveredRemoteResult(result, local), record.operationId);
+                    }
+                }
                 const hydrated = await hydrateInlineUrlResultSafely(result, options.artifactStore);
                 return remoteResultUpdate(hydrated, record.operationId);
             }
@@ -1613,6 +1775,15 @@ export function createLocalParseOperationManager(options) {
             if (record.sourceKind === "local" && record.resultId !== null) {
                 return completedLocalParse(await recoverLocalArtifact(record));
             }
+            if (record.sourceKind === "url" && record.resultId !== null) {
+                try {
+                    return recoveredRemoteParse(record, await recoverLocalArtifact(record));
+                }
+                catch (error) {
+                    if (options.remoteClient === undefined)
+                        throw error;
+                }
+            }
             if (record.sourceKind === "url" && options.remoteClient !== undefined) {
                 const result = await options.remoteClient.status(record.operationId, 0, signal);
                 const hydrated = await hydrateInlineUrlResultSafely(result, options.artifactStore);
@@ -1624,6 +1795,18 @@ export function createLocalParseOperationManager(options) {
     return new OperationManager({
         journal: options.journal,
         driver,
+        presentResult: (record, canonicalResult) => presentRetainedResult(canonicalResult, record.resultDeliveryEffective, async (resultId, byteOffset) => {
+            if (options.artifactStore.mintReadCursor === undefined) {
+                throw managerError("LOCAL_RESULT_INTEGRITY_FAILED", "The retained result cursor capability is unavailable.", {
+                    operationCreated: record.operationId !== null,
+                    fileUploaded: record.fileUploaded,
+                    parserStarted: record.parserStarted,
+                    billed: record.billed,
+                    contentReleased: record.contentReleased,
+                });
+            }
+            return options.artifactStore.mintReadCursor(resultId, byteOffset);
+        }),
         now: () => now().getTime(),
         sleep: options.sleep,
     });

package/dist/path-normalization.d.ts

@@ -0,0 +1,5 @@
+export declare class PathNormalizationError extends Error {
+    readonly code = "INVALID_WINDOWS_PATH";
+    constructor();
+}
+export declare function normalizePlatformPath(value: string, platform?: NodeJS.Platform): string;

package/dist/path-normalization.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+const MSYS_DRIVE_PATH = /^\/([A-Za-z])(?:\/|$)/u;
+export class PathNormalizationError extends Error {
+    code = "INVALID_WINDOWS_PATH";
+    constructor() {
+        super("Use an absolute Windows drive path such as C:\\Reports or exact MSYS syntax such as /c/Reports.");
+        this.name = "PathNormalizationError";
+    }
+}
+export function normalizePlatformPath(value, platform = process.platform) {
+    if (platform !== "win32")
+        return value;
+    if (value.startsWith("//") || value.startsWith("\\\\"))
+        return value;
+    const match = MSYS_DRIVE_PATH.exec(value);
+    if (match !== null) {
+        const drive = match[1].toUpperCase();
+        const remainder = value.slice(match[0].length).replaceAll("/", "\\");
+        return path.win32.normalize(`${drive}:\\${remainder}`);
+    }
+    if (value.startsWith("/") || value.startsWith("\\")) {
+        throw new PathNormalizationError();
+    }
+    return value;
+}

package/dist/path-security.d.ts

@@ -9,6 +9,7 @@ export interface OpenAllowedFileOptions {
     workspace: string;
     extraRoots?: readonly string[];
     homeDirectory?: string;
+    platform?: NodeJS.Platform;
     fileSystem?: PathSecurityFileSystem;
 }
 export interface OpenedAllowedFile {
@@ -19,5 +20,5 @@ export interface OpenedAllowedFile {
     createReadStream(): ReadStream;
     close(): Promise<void>;
 }
-export declare function splitAllowedRoots(value: string | undefined): string[];
+export declare function splitAllowedRoots(value: string | undefined, platform?: NodeJS.Platform): string[];
 export declare function openAllowedFile(input: string, options: OpenAllowedFileOptions): Promise<OpenedAllowedFile>;