@akira-tl/forgerelay 0.1.0

package/dist/git-worktrees.js

@@ -0,0 +1,255 @@
+import { randomBytes } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, realpath, rm, stat } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { assertAllowedPath, isPathInsideRoot } from "./roots.js";
+const execFileAsync = promisify(execFile);
+export class GitWorktreeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GitWorktreeError";
+    }
+}
+export async function createManagedWorktree(input) {
+    const sourcePath = assertAllowedPath(input.sourcePath, input.config.allowedRoots);
+    try {
+        const sourceStats = await stat(sourcePath);
+        if (!sourceStats.isDirectory()) {
+            throw new GitWorktreeError("GIT_REPOSITORY_NOT_FOUND", `Cannot open workspace in worktree mode because the source path is not a directory: ${input.sourcePath}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof GitWorktreeError)
+            throw error;
+        throw new GitWorktreeError("GIT_REPOSITORY_NOT_FOUND", `Cannot open workspace in worktree mode because the source path does not exist: ${input.sourcePath}`);
+    }
+    const { sourceRoot, baseRef, baseSha, targetBranch } = await resolveManagedWorktreeBase(input);
+    const dirtySource = (await git(["status", "--porcelain=v1"], sourceRoot)).trim().length > 0;
+    const worktreeId = randomBytes(4).toString("hex");
+    const worktreePath = managedWorktreePath({
+        worktreeRoot: input.config.worktreeRoot,
+        repoRoot: sourceRoot,
+        worktreeId,
+    });
+    const branch = managedWorktreeBranch({ repoRoot: sourceRoot, worktreeId });
+    await mkdir(input.config.worktreeRoot, { recursive: true });
+    assertAllowedPath(worktreePath, [input.config.worktreeRoot]);
+    try {
+        await git(["worktree", "add", "-b", branch, worktreePath, baseSha], sourceRoot);
+    }
+    catch (error) {
+        await rm(worktreePath, { recursive: true, force: true });
+        const message = error instanceof Error ? error.message : String(error);
+        throw new GitWorktreeError("GIT_WORKTREE_CREATE_FAILED", `Git failed to create the managed worktree. ${message}`);
+    }
+    return {
+        sourceRoot,
+        path: worktreePath,
+        baseRef,
+        baseSha,
+        branch,
+        targetBranch,
+        dirtySource,
+        detached: false,
+        managed: true,
+    };
+}
+export async function closeManagedWorktree(input) {
+    const sourceRoot = assertAllowedPath(input.worktree.sourceRoot, input.config.allowedRoots);
+    const worktreePath = assertAllowedPath(input.worktree.path, [input.config.worktreeRoot]);
+    const sourceBranch = await currentBranch(sourceRoot);
+    if (sourceBranch !== input.worktree.targetBranch) {
+        throw new GitWorktreeError("GIT_WORKTREE_SOURCE_BRANCH_CHANGED", `Cannot close worktree because the source checkout is on branch ${JSON.stringify(sourceBranch)} instead of target branch ${JSON.stringify(input.worktree.targetBranch)}. Switch the source checkout back to the target branch and retry.`);
+    }
+    const sourceDirty = (await git(["status", "--porcelain=v1"], sourceRoot)).trim().length > 0;
+    if (sourceDirty) {
+        throw new GitWorktreeError("GIT_WORKTREE_SOURCE_DIRTY", "Cannot close worktree because the source checkout has uncommitted changes. Commit or stash them first; the managed worktree is unchanged.");
+    }
+    const worktreeBranch = await currentBranch(worktreePath);
+    if (worktreeBranch !== input.worktree.branch) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", `Cannot close worktree because it is on branch ${JSON.stringify(worktreeBranch)} instead of its managed branch ${JSON.stringify(input.worktree.branch)}.`);
+    }
+    let committed = false;
+    if ((await git(["status", "--porcelain=v1"], worktreePath)).trim().length > 0) {
+        await git(["add", "-A"], worktreePath);
+        try {
+            await git(["commit", "-m", input.commitMessage], worktreePath);
+            committed = true;
+        }
+        catch (error) {
+            throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", `Git failed to commit the managed worktree before closing it. ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if ((await git(["status", "--porcelain=v1"], worktreePath)).trim().length > 0) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", "Cannot close worktree because it still has uncommitted changes after the close commit. A Git hook may have modified files; inspect and verify the worktree, then retry.");
+    }
+    const sourceBranchBeforeMerge = await currentBranch(sourceRoot);
+    if (sourceBranchBeforeMerge !== input.worktree.targetBranch) {
+        throw new GitWorktreeError("GIT_WORKTREE_SOURCE_BRANCH_CHANGED", `Cannot close worktree because the source checkout changed to branch ${JSON.stringify(sourceBranchBeforeMerge)} while the worktree was being finalized. The source checkout was not merged.`);
+    }
+    if ((await git(["status", "--porcelain=v1"], sourceRoot)).trim().length > 0) {
+        throw new GitWorktreeError("GIT_WORKTREE_SOURCE_DIRTY", "Cannot close worktree because the source checkout changed while the worktree was being finalized. The source checkout was not merged; commit or stash those changes and retry.");
+    }
+    const sourceHead = (await git(["rev-parse", "HEAD"], sourceRoot)).trim();
+    const commitSha = (await git(["rev-parse", "HEAD"], worktreePath)).trim();
+    if (!(await isAncestor(sourceHead, commitSha, sourceRoot))) {
+        throw new GitWorktreeError("GIT_WORKTREE_DIVERGED", `Cannot close worktree because ${input.worktree.targetBranch} advanced independently of ${input.worktree.branch}. Rebase the worktree branch onto ${input.worktree.targetBranch} inside the worktree, resolve and verify there, then retry. The source checkout was not modified.`);
+    }
+    try {
+        await git(["merge", "--ff-only", input.worktree.branch], sourceRoot);
+    }
+    catch (error) {
+        throw new GitWorktreeError("GIT_WORKTREE_DIVERGED", `Git could not fast-forward ${input.worktree.targetBranch} to ${input.worktree.branch}. The source checkout was not put into a merge-conflict state. ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const mergedSha = (await git(["rev-parse", "HEAD"], sourceRoot)).trim();
+    try {
+        await git(["worktree", "remove", worktreePath], sourceRoot);
+    }
+    catch (error) {
+        throw new GitWorktreeError("GIT_WORKTREE_CLOSE_FAILED", `Changes were merged into ${input.worktree.targetBranch}, but ForgeRelay could not remove the managed worktree. The branch and workspace are preserved so cleanup can be retried. ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let cleanupWarning;
+    try {
+        await git(["branch", "-d", input.worktree.branch], sourceRoot);
+    }
+    catch (error) {
+        cleanupWarning = `The worktree was removed and its changes were merged, but Git could not delete branch ${input.worktree.branch}. Delete that already-merged branch manually if desired. ${error instanceof Error ? error.message : String(error)}`;
+    }
+    return {
+        sourceRoot,
+        path: worktreePath,
+        branch: input.worktree.branch,
+        targetBranch: input.worktree.targetBranch,
+        commitSha,
+        mergedSha,
+        committed,
+        cleanupWarning,
+    };
+}
+export async function resolveManagedWorktreeBase(input) {
+    const sourcePath = assertAllowedPath(input.sourcePath, input.config.allowedRoots);
+    const sourceRoot = await resolveGitRoot(sourcePath, input.config.allowedRoots);
+    const resolved = await resolveWorktreeBase(sourceRoot, input.baseRef);
+    return { sourceRoot, ...resolved };
+}
+async function resolveGitRoot(path, allowedRoots) {
+    try {
+        const output = await git(["rev-parse", "--show-toplevel"], path);
+        return await assertGitRootAllowed(output.trim(), allowedRoots);
+    }
+    catch (error) {
+        if (isGitUnavailable(error)) {
+            throw new GitWorktreeError("GIT_NOT_AVAILABLE", "Cannot open workspace in worktree mode because Git is not available on this machine.");
+        }
+        throw new GitWorktreeError("GIT_REPOSITORY_NOT_FOUND", `Cannot open workspace in worktree mode because this path is not inside a Git repository: ${path}. Use mode=\"checkout\" to work directly in this directory, or initialize Git and create an initial commit first.`);
+    }
+}
+async function assertGitRootAllowed(gitRoot, allowedRoots) {
+    try {
+        return assertAllowedPath(gitRoot, allowedRoots);
+    }
+    catch {
+        const canonicalGitRoot = await realpath(gitRoot);
+        for (const allowedRoot of allowedRoots) {
+            const canonicalAllowedRoot = await realpath(allowedRoot).catch(() => undefined);
+            if (!canonicalAllowedRoot || !isPathInsideRoot(canonicalGitRoot, canonicalAllowedRoot)) {
+                continue;
+            }
+            const logicalGitRoot = resolve(allowedRoot, relative(canonicalAllowedRoot, canonicalGitRoot));
+            return assertAllowedPath(logicalGitRoot, allowedRoots);
+        }
+        return assertAllowedPath(canonicalGitRoot, allowedRoots);
+    }
+}
+async function resolveWorktreeBase(sourceRoot, requestedBaseRef) {
+    const targetBranch = requestedBaseRef && requestedBaseRef !== "HEAD"
+        ? normalizeLocalBranchName(requestedBaseRef)
+        : await currentBranch(sourceRoot);
+    if (!targetBranch) {
+        throw new GitWorktreeError("GIT_WORKTREE_SOURCE_DETACHED", "Cannot create a managed worktree from a detached source checkout. Switch the source checkout to the branch that should receive the finished work first.");
+    }
+    try {
+        const baseSha = (await git(["rev-parse", "--verify", `refs/heads/${targetBranch}^{commit}`], sourceRoot)).trim();
+        return {
+            baseRef: requestedBaseRef ?? "HEAD",
+            baseSha,
+            targetBranch,
+        };
+    }
+    catch {
+        if (!requestedBaseRef || requestedBaseRef === "HEAD") {
+            throw new GitWorktreeError("GIT_REPOSITORY_HAS_NO_COMMITS", "Cannot open workspace in worktree mode because the current branch has no commits yet. Create an initial commit first, or use checkout mode.");
+        }
+        throw new GitWorktreeError("GIT_INVALID_BASE_REF", `Cannot create a managed worktree because baseRef ${JSON.stringify(requestedBaseRef)} is not a local branch. Managed worktrees must start from the local branch they will eventually merge back into.`);
+    }
+}
+async function currentBranch(cwd) {
+    try {
+        return (await git(["symbolic-ref", "--quiet", "--short", "HEAD"], cwd)).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function normalizeLocalBranchName(value) {
+    return value.startsWith("refs/heads/") ? value.slice("refs/heads/".length) : value;
+}
+async function isAncestor(ancestor, descendant, cwd) {
+    try {
+        await git(["merge-base", "--is-ancestor", ancestor, descendant], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function managedWorktreePath(input) {
+    const repoName = sanitizePathSegment(basename(input.repoRoot)) || "repo";
+    return join(input.worktreeRoot, `${repoName}-${input.worktreeId}`);
+}
+function managedWorktreeBranch(input) {
+    const repoName = sanitizeGitBranchSegment(basename(input.repoRoot)) || "repo";
+    return `forgerelay/${repoName}-${input.worktreeId}`;
+}
+function sanitizeGitBranchSegment(value) {
+    return value
+        .replace(/[^a-zA-Z0-9_-]+/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "")
+        .slice(0, 80);
+}
+function sanitizePathSegment(value) {
+    return value
+        .replace(/[^a-zA-Z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+async function git(args, cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", args, {
+            cwd,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (error) {
+        if (isGitUnavailable(error))
+            throw error;
+        const stderr = typeof error === "object" && error && "stderr" in error
+            ? String(error.stderr ?? "").trim()
+            : "";
+        const stdout = typeof error === "object" && error && "stdout" in error
+            ? String(error.stdout ?? "").trim()
+            : "";
+        const details = stderr || stdout || (error instanceof Error ? error.message : String(error));
+        throw new Error(details);
+    }
+}
+function isGitUnavailable(error) {
+    return Boolean(typeof error === "object" &&
+        error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/git.js

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export async function git(cwd, args, options = {}) {
+    const { stdout, stderr } = await execFileAsync("git", args, {
+        cwd,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        maxBuffer: options.maxBuffer ?? 10 * 1024 * 1024,
+    });
+    return { stdout, stderr };
+}
+export async function getGitEligibility(cwd) {
+    try {
+        await git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: "not_git",
+            message: "workspace is not inside a git repository",
+        };
+    }
+    const gitRoot = (await git(cwd, ["rev-parse", "--show-toplevel"])).stdout.trim();
+    try {
+        await git(gitRoot, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+    }
+    catch {
+        return {
+            ok: false,
+            gitRoot,
+            reason: "no_head",
+            message: "repository has no HEAD commit",
+        };
+    }
+    return { ok: true, gitRoot };
+}
+export function safeWorkspaceRefSegment(workspaceId) {
+    const safe = workspaceId.replace(/[^A-Za-z0-9._-]/g, "-");
+    return safe.length > 0 ? safe : createHash("sha256").update(workspaceId).digest("hex").slice(0, 16);
+}

package/dist/incoming-artifacts.js

@@ -0,0 +1,378 @@
+import { basename, isAbsolute } from "node:path";
+import { Readable } from "node:stream";
+import { ArtifactError } from "./artifact-error.js";
+const ADAPTER_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
+const OPENAI_FILE_HOSTS = new Set([
+    "files.oaiusercontent.com",
+]);
+// ChatGPT-generated files are served from regional OpenAI-managed Azure storage
+// accounts. Accept that account family only, never arbitrary Azure Blob hosts.
+const OPENAI_REGIONAL_BLOB_HOST_PATTERN = /^oaisdmntpr[a-z0-9]+\.blob\.core\.windows\.net$/u;
+const OPENAI_FILENAME_SAFE_FILE_ID_PATTERN = /^file[-_][A-Za-z0-9][A-Za-z0-9._-]{0,255}$/u;
+const OPENAI_FILE_ID_MAX_LENGTH = 512;
+const OPENAI_FILE_ID_CONTROL_PATTERN = /[\u0000-\u001F\u007F]/u;
+const OPENAI_FILE_KEYS = new Set([
+    "download_url",
+    "file_id",
+    "mime_type",
+    "file_name",
+    "name",
+    "size",
+]);
+const OPENAI_FILE_REDIRECT_LIMIT = 3;
+const OPENAI_FILE_DOWNLOAD_TIMEOUT_MS = 30_000;
+export class IncomingArtifactAdapterRegistry {
+    adapters;
+    constructor(adapters = []) {
+        const ids = new Set();
+        for (const adapter of adapters) {
+            if (!ADAPTER_ID_PATTERN.test(adapter.id)) {
+                throw new ArtifactError("invalid_incoming_adapter", "Incoming artifact adapter IDs must be short lowercase identifiers.");
+            }
+            if (ids.has(adapter.id)) {
+                throw new ArtifactError("duplicate_incoming_adapter", `Incoming artifact adapter '${adapter.id}' is registered more than once.`);
+            }
+            ids.add(adapter.id);
+        }
+        this.adapters = [...adapters];
+    }
+    async open(value) {
+        const matching = [];
+        for (const adapter of this.adapters) {
+            let handles = false;
+            try {
+                handles = adapter.canHandle(value);
+            }
+            catch {
+                throw new ArtifactError("incoming_artifact_adapter_failed", `Incoming artifact adapter '${adapter.id}' failed during recognition.`);
+            }
+            if (handles)
+                matching.push(adapter);
+        }
+        if (matching.length === 0) {
+            throw new ArtifactError("unsupported_incoming_artifact", "No trusted incoming artifact adapter recognized this file reference.");
+        }
+        if (matching.length > 1) {
+            throw new ArtifactError("ambiguous_incoming_artifact", "More than one trusted incoming artifact adapter recognized this file reference.");
+        }
+        const adapter = matching[0];
+        let source;
+        try {
+            source = await adapter.open(value);
+        }
+        catch (error) {
+            if (error instanceof ArtifactError)
+                throw error;
+            throw new ArtifactError("incoming_artifact_open_failed", `Incoming artifact adapter '${adapter.id}' could not open the file reference.`);
+        }
+        try {
+            validateIncomingArtifactSource(source);
+        }
+        catch (error) {
+            source?.stream?.destroy?.();
+            throw error;
+        }
+        return { ...source, adapterId: adapter.id };
+    }
+}
+export function createOpenAIIncomingArtifactAdapter(options = {}) {
+    const fetchFile = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? OPENAI_FILE_DOWNLOAD_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+        throw new ArtifactError("invalid_openai_file_adapter", "OpenAI file download timeout must be a positive integer.");
+    }
+    return {
+        id: "openai-file",
+        canHandle: isOpenAIFileReferenceCandidate,
+        async open(value) {
+            const reference = normalizeOpenAIFileReference(value);
+            let downloadUrl = validateOpenAIFileUrl(reference.download_url);
+            let response;
+            for (let redirect = 0; redirect <= OPENAI_FILE_REDIRECT_LIMIT; redirect += 1) {
+                try {
+                    response = await fetchFile(downloadUrl, {
+                        redirect: "manual",
+                        signal: AbortSignal.timeout(timeoutMs),
+                    });
+                }
+                catch {
+                    throw new ArtifactError("openai_file_download_failed", "ChatGPT file could not be downloaded.");
+                }
+                if (!isRedirectStatus(response.status))
+                    break;
+                const location = response.headers.get("location");
+                await response.body?.cancel().catch(() => undefined);
+                if (!location || redirect === OPENAI_FILE_REDIRECT_LIMIT) {
+                    throw new ArtifactError("openai_file_download_failed", "ChatGPT file download returned an invalid redirect.");
+                }
+                downloadUrl = validateOpenAIFileUrl(new URL(location, downloadUrl).toString());
+            }
+            if (!response?.ok || !response.body) {
+                await response?.body?.cancel().catch(() => undefined);
+                throw new ArtifactError("openai_file_download_failed", "ChatGPT file download did not return file content.");
+            }
+            const responseSize = responseContentLength(response);
+            if (reference.size !== undefined
+                && responseSize !== undefined
+                && reference.size !== responseSize) {
+                await response.body.cancel().catch(() => undefined);
+                throw new ArtifactError("openai_file_size_mismatch", "ChatGPT file metadata did not match the downloaded content.");
+            }
+            const mimeType = reference.mime_type ?? responseMimeType(response);
+            return {
+                name: normalizeOpenAIFileName(reference.file_name, reference.file_id, mimeType),
+                mimeType,
+                size: responseSize ?? reference.size,
+                stream: Readable.fromWeb(response.body),
+            };
+        },
+    };
+}
+export function describeIncomingArtifactValue(value, maxDepth = 4, maxEntries = 20) {
+    const seen = new WeakSet();
+    const describe = (current, depth) => {
+        if (current === null)
+            return { type: "null" };
+        if (current === undefined)
+            return { type: "undefined" };
+        if (typeof current === "boolean")
+            return { type: "boolean" };
+        if (typeof current === "number")
+            return { type: "number", finite: Number.isFinite(current) };
+        if (typeof current === "bigint")
+            return { type: "bigint" };
+        if (typeof current === "function")
+            return { type: "function" };
+        if (typeof current === "symbol")
+            return { type: "symbol" };
+        if (typeof current === "string") {
+            return {
+                type: "string",
+                kind: classifyValueString(current),
+                length: current.length,
+            };
+        }
+        if (seen.has(current))
+            return { type: "cycle" };
+        seen.add(current);
+        if (Array.isArray(current)) {
+            if (depth >= maxDepth) {
+                return { type: "array", length: current.length, items: [], truncated: current.length > 0 };
+            }
+            const items = current.slice(0, maxEntries).map((item) => describe(item, depth + 1));
+            return {
+                type: "array",
+                length: current.length,
+                items,
+                truncated: current.length > items.length,
+            };
+        }
+        const keys = Object.keys(current).sort();
+        if (depth >= maxDepth) {
+            return {
+                type: "object",
+                constructor: safeConstructorName(current),
+                entries: {},
+                truncated: keys.length > 0,
+            };
+        }
+        const entries = {};
+        for (const [index, key] of keys.slice(0, maxEntries).entries()) {
+            let entryValue;
+            try {
+                entryValue = current[key];
+            }
+            catch {
+                entryValue = undefined;
+            }
+            entries[safeValueEntryKey(key, index)] = describe(entryValue, depth + 1);
+        }
+        return {
+            type: "object",
+            constructor: safeConstructorName(current),
+            entries,
+            truncated: keys.length > Object.keys(entries).length,
+        };
+    };
+    return describe(value, 0);
+}
+function validateIncomingArtifactSource(source) {
+    if (!source || typeof source !== "object") {
+        throw new ArtifactError("invalid_incoming_artifact_source", "Incoming artifact adapter returned an invalid source.");
+    }
+    if (typeof source.name !== "string" || source.name.length === 0) {
+        throw new ArtifactError("invalid_incoming_artifact_source", "Incoming artifact adapter must provide a filename.");
+    }
+    if (source.mimeType !== undefined && typeof source.mimeType !== "string") {
+        throw new ArtifactError("invalid_incoming_artifact_source", "Incoming artifact adapter returned an invalid MIME hint.");
+    }
+    if (source.size !== undefined
+        && (!Number.isSafeInteger(source.size) || source.size < 0)) {
+        throw new ArtifactError("invalid_incoming_artifact_source", "Incoming artifact adapter returned an invalid byte size.");
+    }
+    const stream = source.stream;
+    if (!stream || typeof stream[Symbol.asyncIterator] !== "function") {
+        throw new ArtifactError("invalid_incoming_artifact_source", "Incoming artifact adapter must provide an async-readable stream.");
+    }
+}
+function isOpenAIFileReferenceCandidate(value) {
+    if (!isRecord(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length >= 2
+        && keys.every((key) => OPENAI_FILE_KEYS.has(key))
+        && Object.hasOwn(value, "download_url")
+        && Object.hasOwn(value, "file_id");
+}
+function normalizeOpenAIFileReference(value) {
+    if (!isOpenAIFileReferenceCandidate(value)) {
+        throw new ArtifactError("invalid_openai_file_reference", "ChatGPT file reference is malformed.");
+    }
+    const downloadUrl = value.download_url;
+    const fileId = value.file_id;
+    if (typeof downloadUrl !== "string"
+        || typeof fileId !== "string"
+        || !isValidOpenAIFileId(fileId)) {
+        throw new ArtifactError("invalid_openai_file_reference", "ChatGPT file reference is malformed.");
+    }
+    const mimeType = nullableString(value.mime_type);
+    const fileName = nullableString(value.file_name);
+    const nameAlias = nullableString(value.name);
+    if (mimeType === null || fileName === null || nameAlias === null) {
+        throw new ArtifactError("invalid_openai_file_reference", "ChatGPT file reference is malformed.");
+    }
+    const normalizedFileName = normalizeSuppliedOpenAIFileName(fileName);
+    const normalizedNameAlias = normalizeSuppliedOpenAIFileName(nameAlias);
+    if (normalizedFileName
+        && normalizedNameAlias
+        && normalizedFileName !== normalizedNameAlias) {
+        throw new ArtifactError("ambiguous_openai_file_name", "ChatGPT file reference contained conflicting filenames.");
+    }
+    let size;
+    const rawSize = value.size;
+    if (rawSize !== undefined && rawSize !== null) {
+        if (typeof rawSize !== "number" || !Number.isSafeInteger(rawSize) || rawSize < 0) {
+            throw new ArtifactError("invalid_openai_file_reference", "ChatGPT file reference is malformed.");
+        }
+        size = rawSize;
+    }
+    return {
+        download_url: downloadUrl,
+        file_id: fileId,
+        mime_type: mimeType,
+        file_name: normalizedFileName ?? normalizedNameAlias,
+        size,
+    };
+}
+function nullableString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    return typeof value === "string" ? value : null;
+}
+function normalizeOpenAIFileName(suppliedName, fileId, mimeType) {
+    if (suppliedName)
+        return suppliedName;
+    const safeBaseName = OPENAI_FILENAME_SAFE_FILE_ID_PATTERN.test(fileId)
+        ? fileId
+        : "chatgpt-file";
+    return `${safeBaseName}${extensionForMimeType(mimeType) ?? ".bin"}`;
+}
+function isValidOpenAIFileId(value) {
+    return value.length > 0
+        && value.length <= OPENAI_FILE_ID_MAX_LENGTH
+        && !OPENAI_FILE_ID_CONTROL_PATTERN.test(value);
+}
+function normalizeSuppliedOpenAIFileName(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.replaceAll("\\", "/");
+    const candidate = basename(normalized).trim();
+    if (!candidate || candidate === "." || candidate === ".." || candidate.startsWith(".")) {
+        return undefined;
+    }
+    return candidate;
+}
+function extensionForMimeType(mimeType) {
+    switch (mimeType?.toLowerCase()) {
+        case "image/png": return ".png";
+        case "image/jpeg": return ".jpg";
+        case "image/webp": return ".webp";
+        case "image/gif": return ".gif";
+        case "application/pdf": return ".pdf";
+        case "text/plain": return ".txt";
+        case "application/zip": return ".zip";
+        case "application/vnd.openxmlformats-officedocument.wordprocessingml.document": return ".docx";
+        default: return undefined;
+    }
+}
+function validateOpenAIFileUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new ArtifactError("unsafe_openai_file_reference", "ChatGPT file download URL is invalid.");
+    }
+    if (url.protocol !== "https:"
+        || !isTrustedOpenAIFileHost(url.hostname)
+        || (url.port !== "" && url.port !== "443")
+        || url.username !== ""
+        || url.password !== ""
+        || url.hash !== "") {
+        throw new ArtifactError("unsafe_openai_file_reference", "ChatGPT file download URL is outside the trusted file host.");
+    }
+    return url.toString();
+}
+function isTrustedOpenAIFileHost(hostname) {
+    return OPENAI_FILE_HOSTS.has(hostname) || OPENAI_REGIONAL_BLOB_HOST_PATTERN.test(hostname);
+}
+function isRedirectStatus(status) {
+    return status === 301
+        || status === 302
+        || status === 303
+        || status === 307
+        || status === 308;
+}
+function responseMimeType(response) {
+    const value = response.headers.get("content-type")?.split(";", 1)[0]?.trim();
+    return value || undefined;
+}
+function responseContentLength(response) {
+    const value = response.headers.get("content-length");
+    if (!value || !/^\d+$/u.test(value))
+        return undefined;
+    const size = Number(value);
+    return Number.isSafeInteger(size) ? size : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function classifyValueString(value) {
+    if (value.startsWith("data:"))
+        return "data-url";
+    if (isAbsolute(value))
+        return "absolute-path";
+    try {
+        const parsed = new URL(value);
+        if (parsed.protocol === "http:" || parsed.protocol === "https:")
+            return "url";
+    }
+    catch {
+        // Non-URL strings are summarized only by type and length.
+    }
+    return "text";
+}
+function safeValueEntryKey(value, index) {
+    return /^[A-Za-z_][A-Za-z0-9_.-]{0,79}$/u.test(value)
+        ? value
+        : `<redacted-key-${index + 1}>`;
+}
+function safeConstructorName(value) {
+    try {
+        const name = value.constructor?.name;
+        return typeof name === "string" && name.length <= 80 ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}