feat: add inferDownloadExtension and getDefaultDownloadPath utilities

Add shared utilities for inferring file extensions from object content
types when generating default download paths. This is the complement of
adjustFileExtension() in runloop-fe (PR #1714), which strips extensions
for mount paths — this module adds extensions for download paths.

Rules:
- text/binary with no suffix → .txt/.bin
- gzip + .tar suffix → .tgz (not .tar.gz)
- gzip/tar/tgz with mismatched suffix → append correct extension
- All suffix checks are case-insensitive

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jason-rl

src/utils/downloadPath.ts

@@ -0,0 +1,107 @@
+/**
+ * Utilities for inferring download file extensions from content types
+ * and generating default download paths for objects.
+ *
+ * This is the complement of adjustFileExtension() in runloop-fe's
+ * object-mount-utils.ts, which strips extensions for mount paths
+ * (after decompression/extraction). This module adds extensions for
+ * download paths so the saved file reflects the object's content type.
+ */
+
+/** Suffixes considered "already gzip" (case-insensitive) */
+const GZIP_SUFFIXES = new Set([".gz", ".gzip", ".taz", ".tgz"]);
+
+/** Suffixes considered "already tgz" (case-insensitive) */
+const TGZ_SUFFIXES = new Set([".taz", ".tgz"]);
+
+/**
+ * Check if name ends with a compound suffix like .tar.gz or .tar.gzip
+ * (case-insensitive). Returns true if the last two dot-segments match.
+ */
+function hasCompoundTgzSuffix(name: string): boolean {
+  return /\.(tar\.gz|tar\.gzip)$/i.test(name);
+}
+
+/**
+ * Get the suffix of a filename (the part after the last dot).
+ * Returns empty string if no dot or only a leading dot (e.g. ".hidden").
+ */
+function getSuffix(name: string): string {
+  const lastDot = name.lastIndexOf(".");
+  if (lastDot <= 0) return "";
+  return name.slice(lastDot);
+}
+
+/**
+ * Returns true if the name has any dot-separated extension.
+ * A leading dot alone (e.g. ".hidden") does not count as having a suffix.
+ */
+function hasSuffix(name: string): boolean {
+  return getSuffix(name) !== "";
+}
+
+/**
+ * Infer a download filename by appending or adjusting the file extension
+ * based on the object's content_type.
+ *
+ * Rules (suffix comparisons are case-insensitive):
+ * - text   + no suffix → .txt
+ * - binary + no suffix → .bin
+ * - gzip   + suffix is .tar → replace with .tgz
+ * - gzip   + suffix not in {.gz,.gzip,.taz,.tgz,.tar} → append .gz
+ * - tar    + suffix != .tar → append .tar
+ * - tgz    + suffix not in {.tar.gz,.tar.gzip,.taz,.tgz} → append .tgz
+ * - unspecified / undefined → no change
+ */
+export function inferDownloadExtension(
+  name: string,
+  contentType: string | undefined,
+): string {
+  if (!contentType || contentType === "unspecified") return name;
+
+  const suffix = getSuffix(name).toLowerCase();
+
+  switch (contentType) {
+    case "text":
+      return hasSuffix(name) ? name : `${name}.txt`;
+
+    case "binary":
+      return hasSuffix(name) ? name : `${name}.bin`;
+
+    case "gzip":
+      if (suffix === ".tar") {
+        // gzipped tar → .tgz
+        return name.slice(0, -suffix.length) + ".tgz";
+      }
+      if (GZIP_SUFFIXES.has(suffix)) return name;
+      return `${name}.gz`;
+
+    case "tar":
+      if (suffix === ".tar") return name;
+      return `${name}.tar`;
+
+    case "tgz":
+      if (hasCompoundTgzSuffix(name)) return name;
+      if (TGZ_SUFFIXES.has(suffix)) return name;
+      return `${name}.tgz`;
+
+    default:
+      return name;
+  }
+}
+
+/**
+ * Generate a default download path for an object.
+ *
+ * Uses the object's name (or ID as fallback), applies extension inference,
+ * and prepends "./" for a relative path.
+ */
+export function getDefaultDownloadPath(
+  name: string | undefined,
+  id: string,
+  contentType: string | undefined,
+): string {
+  const baseName = name?.trim() || id;
+  const withExtension = inferDownloadExtension(baseName, contentType);
+  return `./${withExtension}`;
+}

tests/__tests__/utils/downloadPath.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Tests for download path utilities
+ */
+
+import { describe, it, expect } from "@jest/globals";
+import {
+  inferDownloadExtension,
+  getDefaultDownloadPath,
+} from "../../../src/utils/downloadPath.js";
+
+describe("inferDownloadExtension", () => {
+  describe("no suffix on name", () => {
+    it("appends .txt for text content type", () => {
+      expect(inferDownloadExtension("myfile", "text")).toBe("myfile.txt");
+    });
+
+    it("appends .bin for binary content type", () => {
+      expect(inferDownloadExtension("myfile", "binary")).toBe("myfile.bin");
+    });
+
+    it("appends .gz for gzip content type", () => {
+      expect(inferDownloadExtension("myfile", "gzip")).toBe("myfile.gz");
+    });
+
+    it("appends .tar for tar content type", () => {
+      expect(inferDownloadExtension("myfile", "tar")).toBe("myfile.tar");
+    });
+
+    it("appends .tgz for tgz content type", () => {
+      expect(inferDownloadExtension("myfile", "tgz")).toBe("myfile.tgz");
+    });
+
+    it("appends .txt for dot-only hidden files with text type", () => {
+      expect(inferDownloadExtension(".hidden", "text")).toBe(".hidden.txt");
+    });
+  });
+
+  describe("suffix matches content type (no change)", () => {
+    it("keeps .gz for gzip", () => {
+      expect(inferDownloadExtension("myfile.gz", "gzip")).toBe("myfile.gz");
+    });
+
+    it("keeps .gzip for gzip", () => {
+      expect(inferDownloadExtension("myfile.gzip", "gzip")).toBe(
+        "myfile.gzip",
+      );
+    });
+
+    it("keeps .taz for gzip", () => {
+      expect(inferDownloadExtension("file.taz", "gzip")).toBe("file.taz");
+    });
+
+    it("keeps .tgz for gzip", () => {
+      expect(inferDownloadExtension("file.tgz", "gzip")).toBe("file.tgz");
+    });
+
+    it("keeps .tar for tar", () => {
+      expect(inferDownloadExtension("myfile.tar", "tar")).toBe("myfile.tar");
+    });
+
+    it("keeps .tgz for tgz", () => {
+      expect(inferDownloadExtension("myfile.tgz", "tgz")).toBe("myfile.tgz");
+    });
+
+    it("keeps .taz for tgz", () => {
+      expect(inferDownloadExtension("myfile.taz", "tgz")).toBe("myfile.taz");
+    });
+
+    it("keeps .tar.gz for tgz", () => {
+      expect(inferDownloadExtension("myfile.tar.gz", "tgz")).toBe(
+        "myfile.tar.gz",
+      );
+    });
+
+    it("keeps .tar.gzip for tgz", () => {
+      expect(inferDownloadExtension("data.tar.gzip", "tgz")).toBe(
+        "data.tar.gzip",
+      );
+    });
+  });
+
+  describe("suffix mismatches content type (appends)", () => {
+    it("appends .gz for gzip when suffix is .txt", () => {
+      expect(inferDownloadExtension("myfile.txt", "gzip")).toBe(
+        "myfile.txt.gz",
+      );
+    });
+
+    it("appends .tar for tar when suffix is .json", () => {
+      expect(inferDownloadExtension("myfile.json", "tar")).toBe(
+        "myfile.json.tar",
+      );
+    });
+
+    it("appends .tgz for tgz when suffix is .bin", () => {
+      expect(inferDownloadExtension("myfile.bin", "tgz")).toBe(
+        "myfile.bin.tgz",
+      );
+    });
+  });
+
+  describe("gzip + .tar special case", () => {
+    it("replaces .tar with .tgz for gzip content type", () => {
+      expect(inferDownloadExtension("archive.tar", "gzip")).toBe(
+        "archive.tgz",
+      );
+    });
+
+    it("replaces .TAR with .tgz for gzip content type (case-insensitive)", () => {
+      expect(inferDownloadExtension("archive.TAR", "gzip")).toBe(
+        "archive.tgz",
+      );
+    });
+  });
+
+  describe("text/binary with existing suffix (no change)", () => {
+    it("keeps .json for text type", () => {
+      expect(inferDownloadExtension("myfile.json", "text")).toBe("myfile.json");
+    });
+
+    it("keeps .yaml for text type", () => {
+      expect(inferDownloadExtension("config.yaml", "text")).toBe("config.yaml");
+    });
+
+    it("keeps .wasm for binary type", () => {
+      expect(inferDownloadExtension("myfile.wasm", "binary")).toBe(
+        "myfile.wasm",
+      );
+    });
+
+    it("keeps .exe for binary type", () => {
+      expect(inferDownloadExtension("app.exe", "binary")).toBe("app.exe");
+    });
+  });
+
+  describe("case insensitivity", () => {
+    it("recognizes .GZ as matching gzip", () => {
+      expect(inferDownloadExtension("myfile.GZ", "gzip")).toBe("myfile.GZ");
+    });
+
+    it("recognizes .TAR as matching tar", () => {
+      expect(inferDownloadExtension("myfile.TAR", "tar")).toBe("myfile.TAR");
+    });
+
+    it("recognizes .Tgz as matching tgz", () => {
+      expect(inferDownloadExtension("myfile.Tgz", "tgz")).toBe("myfile.Tgz");
+    });
+
+    it("recognizes .TAR.GZIP as matching tgz", () => {
+      expect(inferDownloadExtension("data.TAR.GZIP", "tgz")).toBe(
+        "data.TAR.GZIP",
+      );
+    });
+
+    it("recognizes .TAR.GZ as matching tgz", () => {
+      expect(inferDownloadExtension("data.TAR.GZ", "tgz")).toBe("data.TAR.GZ");
+    });
+
+    it("recognizes .Taz as matching tgz", () => {
+      expect(inferDownloadExtension("data.Taz", "tgz")).toBe("data.Taz");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("returns name unchanged for unspecified content type", () => {
+      expect(inferDownloadExtension("myfile", "unspecified")).toBe("myfile");
+    });
+
+    it("returns name unchanged for undefined content type", () => {
+      expect(inferDownloadExtension("myfile", undefined)).toBe("myfile");
+    });
+
+    it("returns name unchanged for empty string content type", () => {
+      expect(inferDownloadExtension("myfile", "")).toBe("myfile");
+    });
+  });
+});
+
+describe("getDefaultDownloadPath", () => {
+  it("uses name with extension inference", () => {
+    expect(getDefaultDownloadPath("myfile", "obj_123", "text")).toBe(
+      "./myfile.txt",
+    );
+  });
+
+  it("falls back to id when name is undefined", () => {
+    expect(getDefaultDownloadPath(undefined, "obj_123", "text")).toBe(
+      "./obj_123.txt",
+    );
+  });
+
+  it("falls back to id when name is empty", () => {
+    expect(getDefaultDownloadPath("", "obj_123", "tar")).toBe("./obj_123.tar");
+  });
+
+  it("falls back to id when name is whitespace", () => {
+    expect(getDefaultDownloadPath("  ", "obj_123", "binary")).toBe(
+      "./obj_123.bin",
+    );
+  });
+
+  it("trims name before processing", () => {
+    expect(getDefaultDownloadPath("  myfile  ", "obj_123", "gzip")).toBe(
+      "./myfile.gz",
+    );
+  });
+
+  it("preserves existing matching extension", () => {
+    expect(getDefaultDownloadPath("data.tar.gz", "obj_123", "tgz")).toBe(
+      "./data.tar.gz",
+    );
+  });
+
+  it("handles no content type", () => {
+    expect(getDefaultDownloadPath("myfile", "obj_123", undefined)).toBe(
+      "./myfile",
+    );
+  });
+});