DMG Customization

/**
 * Apply comprehensive customization to DMG file
 * Handles backgrounds, icons, window layout, compression, and content positioning
 * @param config - Complete DMG builder configuration
 * @returns Promise resolving to boolean indicating success
 */
function customizeDmg(config: DmgBuilderConfig): Promise<boolean>;

interface DmgBuilderConfig {
  /** Path to the .app bundle being packaged */
  appPath: string;
  /** Output path for the generated DMG file */
  artifactPath: string;
  /** Volume name for the mounted DMG */
  volumeName: string;
  /** DMG appearance and behavior specification */
  specification: DmgOptions;
  /** MacPackager instance for resource access */
  packager: MacPackager;
}

import { customizeDmg } from "dmg-builder";

const config = {
  appPath: "/path/to/MyApp.app",
  artifactPath: "/output/MyApp-1.0.0.dmg", 
  volumeName: "MyApp 1.0.0",
  specification: {
    background: "/path/to/background.tiff",
    iconSize: 80,
    window: { 
      position: { x: 100, y: 400 },
      size: { width: 600, height: 400 }
    },
    contents: [
      { path: "/path/to/MyApp.app", x: 150, y: 200, type: "file" },
      { path: "/Applications", x: 450, y: 200, type: "link" }
    ]
  },
  packager: macPackager
};

const success = await customizeDmg(config);

/**
 * Compute appropriate background image path for DMG
 * Auto-detects background.tiff or background.png in build resources
 * @param packager - Platform packager with access to build resources
 * @returns Promise resolving to background image path
 */
function computeBackground(packager: PlatformPackager<any>): Promise<string>;

import { computeBackground } from "dmg-builder";

// Automatic background detection
const backgroundPath = await computeBackground(packager);

// Manual background processing with retina support
const processedBackground = await transformBackgroundFileIfNeed(
  "/path/to/background.png",
  tmpDir
);

/**
 * Extract image dimensions using macOS sips command
 * Provides accurate pixel dimensions for background images
 * @param background - Path to image file (TIFF, PNG, JPG, etc.)
 * @returns Promise resolving to width and height in pixels
 * @throws Error if sips fails or cannot parse dimensions
 */
function getImageSizeUsingSips(background: string): Promise<{width: number, height: number}>;

import { getImageSizeUsingSips } from "dmg-builder";

// Get dimensions for window auto-sizing
const { width, height } = await getImageSizeUsingSips("/path/to/background.tiff");

// Auto-size window to background image
const windowConfig = {
  position: { x: 400, y: Math.round((1440 - height) / 2) }, // Center vertically
  size: { width, height }
};

/**
 * Complete DMG build configuration for dmgbuild Python library
 * Includes all visual and structural customization options
 */
interface DmgBuildConfig {
  /** DMG volume title */
  title: string;
  /** Path to DMG icon file */
  icon?: string | null;
  /** Path to badge icon overlay */
  "badge-icon"?: string | null;
  /** Path to background image */
  background?: string | null;
  /** Background color (hex) when no background image */
  "background-color"?: string | null;
  /** Icon size in pixels */
  "icon-size"?: number | null;
  /** Text size for icon labels (points) */
  "text-size"?: number | null;
  /** DMG window configuration */
  window?: {
    position?: { x?: number; y?: number };
    size?: { width?: number; height?: number };
  };
  /** DMG format (UDZO, UDRO, UDBZ, etc.) */
  format?: string;
  /** Filesystem type (HFS+, APFS) */
  filesystem?: string;
  /** Compression level (0-9) */
  "compression-level"?: number | null;
  /** Path to license file */
  license?: string | null;
  /** File and folder layout configuration */
  contents?: Array<{
    /** Path to file/directory to include */
    path: string;
    /** X position in DMG window */
    x: number;
    /** Y position in DMG window */
    y: number;
    /** Display name (optional) */
    name?: string;
    /** Item type */
    type?: "file" | "link" | "position";
    /** Hide file extension */
    hide_extension?: boolean;
    /** Hide item from view */
    hidden?: boolean;
  }>;
}

const contents = [
  // Application positioned on left
  {
    path: "/path/to/MyApp.app",
    x: 130,
    y: 220,
    name: "MyApp.app",
    type: "file"
  },
  // Applications folder link on right
  {
    path: "/Applications", 
    x: 410,
    y: 220,
    type: "link"
  },
  // Additional files
  {
    path: "/path/to/ReadMe.txt",
    x: 270,
    y: 320,
    name: "Read Me",
    type: "file"
  },
  // Hidden positioning element
  {
    path: "/path/to/invisible", 
    x: 500,
    y: 100,
    type: "position",
    hidden: true
  }
];

// Internal implementation uses Python subprocess
const pythonPath = process.env.PYTHON_PATH || "python3";
await exec(pythonPath, [
  path.join(getDmgVendorPath(), "run_dmgbuild.py"),
  "-s", settingsFile,
  volumeName,
  artifactPath
]);