@kitschpatrol/aphex 0.1.0

package/dist/assets/applescript-gui.applescript

@@ -0,0 +1,236 @@
+-- Exports images from Photos via automated GUI manipulation
+-- It's an unsavory approach, but no other means of automation seems to yield higher quality edited image exports (so far)
+-- Arguments are passed in their order of appearance in the GUI, and expect values exactly matching the UI strings in Photos.app
+-- Accepts an individual photo UUID, or an album UUID (use aphex-swift to look up identifiers / UUIDs)
+on run { uuid, exportDirectory, photoKind, jpegQuality, tiffBitDepth, colorProfile, photoSize, maxSizeType, maxSizeValue, includeMetadata, includeLocation , fileName, sequentialPrefix, subfolderFormat}
+		
+	tell application "System Events"
+		set wasRunning to (name of processes) contains "Photos"
+	end tell
+	
+	tell application "Photos"
+		activate
+		
+		-- Reset selection and view		
+		tell application "System Events"
+			tell process "Photos"
+				repeat until exists menu bar 1
+					delay 0.25
+				end repeat
+				click menu item "Library" of menu 1 of menu item "Photos" of menu 1 of menu bar item "View" of menu bar 1
+				delay 0.1
+				click menu item "Deselect All" of menu 1 of menu bar item "Edit" of menu bar 1
+			end tell
+		end tell
+		
+		-- Select photo or album for export by UUID
+		try
+			spotlight media item id (uuid)
+		on error
+			try
+				spotlight album id (uuid)
+			end try
+		end try
+		
+		if (count of selection) is 0 then
+			log "No photos to export"
+			if not wasRunning then
+				tell application "Photos" to quit
+			end if
+			return
+		end if
+	end tell
+	
+	-- Create export destination directory if necessary
+	-- try
+	-- 	do shell script "mkdir -p " & quoted form of exportDirectory
+	-- on error errMsg number errNum
+	-- 	display alert "Error creating directory" message errMsg & " (Error " & errNum & ")"
+	-- end try
+	
+	-- Store initial state for logging
+	set initialFiles to filesInExportDirectory(exportDirectory)
+	
+	tell application "System Events"
+		tell process "Photos"
+			
+			-- Export command
+			repeat until exists menu bar 1
+				delay 0.1
+			end repeat
+			click menu item 1 of menu "Export" of menu item "Export" of menu "File" of menu bar item "File" of menu bar 1
+			
+			repeat until exists sheet 1 of window 1
+				delay 0.1
+			end repeat
+			
+			-- Set export preferences
+			tell sheet 1 of window 1
+				tell group "Photos"
+					
+					-- Ensure the disclosure is open
+					if not (exists pop up button "Color Profile:") then
+						click UI element 3
+						delay 0.5
+					end if
+					
+					tell pop up button "Photo Kind:"
+						if value is not photoKind then
+							click
+							click menu item photoKind of menu 1
+							delay 0.5
+						end if
+					end tell
+					
+					if photoKind is "JPEG" then
+						tell pop up button "JPEG Quality:"
+							if value is not jpegQuality then
+								click
+								click menu item jpegQuality of menu 1
+								delay 0.5
+							end if
+						end tell
+					end if
+					
+					if photoKind is "TIFF" then
+						tell checkbox "16 Bit"
+							if (value as boolean) is not (tiffBitDepth is 16) then
+								click
+							end if
+						end tell
+					end if
+					
+					tell pop up button "Color Profile:"
+						if value is not colorProfile then
+							click
+							click menu item colorProfile of menu 1
+							delay 0.5
+						end if
+					end tell
+					
+					tell pop up button "Size:"
+						if value is not photoSize then
+							click
+							click menu item photoSize of menu 1
+							delay 0.5
+						end if
+					end tell
+					
+					if photoSize is "Custom" then
+						tell group 1
+							
+							tell pop up button "Max"
+								if value is not maxSizeType then
+									click
+									click menu item maxSizeType of menu 1
+									delay 0.5
+								end if
+							end tell
+							
+							tell text field 1
+								if value is not maxSizeValue then
+									set value of attribute "AXFocused" to true
+									set value of attribute "AXValue" to maxSizeValue as string
+									perform action "AXConfirm"
+								end if
+							end tell
+							
+						end tell
+					end if
+					
+				end tell
+				
+				tell group "Info"
+					tell checkbox "Title, Keywords, and Caption"
+						if (value as boolean) is not (includeMetadata as boolean) then
+							click
+						end if
+					end tell
+					tell checkbox "Location Information"
+						if (value as boolean) is not (includeLocation as boolean) then
+							click
+						end if
+					end tell
+				end tell
+				
+				tell group "File Naming"
+					tell pop up button "File Name:"
+						if value is not fileName then
+							click
+							click menu item fileName of menu 1
+							delay 0.5
+						end if
+					end tell
+					if fileName is "Sequential" then
+						-- why not "Sequential Prefix:"?
+						tell text field 1
+							if value is not sequentialPrefix then
+								set value of attribute "AXFocused" to true
+								set value of attribute "AXValue" to sequentialPrefix
+								perform action "AXConfirm"
+							end if
+						end tell
+					end if
+					tell pop up button "Subfolder Format:"
+						if value is not subfolderFormat then
+							click
+							click menu item subfolderFormat of menu 1
+							delay 0.5
+						end if
+					end tell
+				end tell
+				
+				delay 0.5
+				click button "Export"
+				
+			end tell
+			
+			-- Set export location
+			repeat until exists sheet 1 of window 1
+				delay 0.1
+			end repeat
+			
+			tell sheet 1 of window 1
+				keystroke "g" using {command down, shift down}
+				repeat until exists sheet 1
+					delay 0.1
+				end repeat
+				tell sheet 1
+					keystroke exportDirectory
+					key code 76
+				end tell
+				
+				-- Getting stuck here...
+				delay 1
+				click button "Export"
+			end tell
+			
+			-- Wait for the export to finish, but allow a few second for the progress indicator to appear
+			set startTime to (current date)
+			repeat until (not (exists progress indicator 1 of group 2 of toolbar 1 of window 1)) and ((current date) - startTime) > 2
+				delay 0.25
+			end repeat
+			
+		end tell
+	end tell
+	
+	-- Clean up
+	if not wasRunning then
+		tell application "Photos" to quit
+	end if
+	
+	-- Log the exported files	
+	set currentFiles to filesInExportDirectory(exportDirectory)
+	repeat with aFile in currentFiles
+		if (initialFiles does not contain aFile) then
+			set end of initialFiles to aFile
+			log aFile
+		end if
+	end repeat
+	
+end run
+
+-- Handler to get list of files excluding hidden ones
+on filesInExportDirectory(exportDirectory)
+	return paragraphs of (do shell script "find " & quoted form of exportDirectory & " -type f \\! -name \".*\"")
+end filesInExportDirectory

package/dist/index.d.ts

@@ -0,0 +1,373 @@
+import { ExifTool } from "exiftool-vendored";
+import { ILogBasic, ILogLayer } from "lognow";
+import { OmitDeep, PartialDeep, Simplify } from "type-fest";
+
+//#region src/aphex-swift/cli-bridge.d.ts
+/**
+ * Start an interactive session with aphex-swift.
+ * Commands will be sent to this persistent process instead of spawning new ones.
+ * @throws {Error} If the session is already active or fails to start
+ */
+declare function interactiveSessionStart(): Promise<void>;
+/**
+ * Stop the interactive session if one is active.
+ */
+declare function interactiveSessionStop(): Promise<void>;
+/**
+ * TypeScript type definition for ResourceInfo from the Swift implementation
+ */
+type ResourceInfo = {
+  contentType: string;
+  fileName: string;
+  filePath: string;
+  fileSize: number;
+  height: number;
+  width: number;
+};
+/**
+ * TypeScript type definition for the JSON representation of a PHAsset
+ * from the iOS Photos framework (CodablePHAsset)
+ */
+type PhotoInfo = {
+  dateCreated: Date;
+  dateModified: Date;
+  edited?: ResourceInfo;
+  favorite: boolean;
+  hidden: boolean;
+  original: ResourceInfo;
+  title?: string;
+  uuid: string;
+};
+type AlbumInfo = {
+  dateEnd?: Date;
+  dateStart?: Date;
+  estimatedAssetCount: number;
+  path: string;
+  subtype: number;
+  title: string;
+  type: number;
+  uuid: string;
+};
+/**
+ * Get photo asset information for given identifiers (ID, filename, album name, or photo path)
+ * @throws {Error} If the command fails
+ */
+declare function aphexPhotoInfo(identifiers: string | string[], caseSensitive?: boolean): Promise<PhotoInfo[]>;
+/**
+ * Get album info
+ * @throws {Error} If the command fails
+ */
+declare function aphexAlbumInfo(identifiers: string | string[], caseSensitive?: boolean): Promise<AlbumInfo[]>;
+//#endregion
+//#region src/utilities/image/mime.d.ts
+declare const IMAGE_MIME_TYPES: readonly ["arw", "avif", "bmp", "cr2", "cr3", "crw", "tga", "dng", "gif", "heic", "heif", "jpeg", "nef", "pef", "png", "psd", "svg+xml", "tiff", "webp"];
+type ImageMimeType = (typeof IMAGE_MIME_TYPES)[number];
+//#endregion
+//#region src/pipeline/engines/applescript-gui.d.ts
+/**
+ * Mirrors the export UI in Note that note that some options are contingent on others.
+ *
+ * The AppleScript implementation is smart about only "clicking" the necessary
+ * options in the GUI.
+ */
+type ExportViaAppleScriptGuiOptions = {
+  /** "Color Profile" Drop Down */colorProfile: 'AdobeRGB' | 'Display P3' | 'Most Compatible' | 'Original' | 'sRGB'; /** "File Name" Drop Down */
+  fileName: 'Album Name With Number' | 'Sequential' | 'Use File Name' | 'Use Title'; /** "Include Location Information" Checkbox */
+  includeLocation: boolean; /** "Include Title, Keywords, and Caption" Checkbox */
+  includeMetadata: boolean;
+  /**
+   * "JPEG Quality" Drop Down
+   *
+   * Only applies if `photoKind` is `JPEG`
+   */
+  jpegQuality: 'High' | 'Low (smallest Size)' | 'Maximum' | 'Medium';
+  /**
+   * "Size Max" Drop Down
+   *
+   * Only applies if `photoSize` is `Custom`
+   */
+  maxSizeType: 'Dimension' | 'Height' | 'Width';
+  /**
+   * "Size Max of" text field
+   *
+   * Only applies if `photoSize` is `Custom`
+   */
+  maxSizeValue: number; /** "Photo Kind" Drop Down */
+  photoKind: 'HEIC' | 'JPEG' | 'PNG' | 'TIFF'; /** "Size" Drop Down */
+  photoSize: 'Custom' | 'Full Size' | 'Large' | 'Medium' | 'Small';
+  /**
+   * "Sequential Prefix" Text Field
+   *
+   * Only applies if `fileName` is `Sequential`
+   */
+  sequentialPrefix: string; /** "Subfolder Format" Drop Down */
+  subfolderFormat: 'Moment Name' | 'None';
+  /**
+   * "16 Bit" Checkbox
+   *
+   * Only applies if `photoKind` is `TIFF`
+   */
+  tiffBitDepth: 8 | 16;
+};
+//#endregion
+//#region src/pipeline/image-export.d.ts
+type ExportEngine = 'applescript' | 'file-system' | 'photos-gui' | 'swift-photokit';
+type ExportEngineOptions = ExportEngine | Partial<Record<ImageMimeType, ExportEngine>>;
+type ExportApplePhotoOptions = {
+  appleScriptGuiOptions: ExportViaAppleScriptGuiOptions;
+  engineEdited: ExportEngineOptions;
+  engineEditedAlpha: ExportEngineOptions;
+  engineOriginal: ExportEngineOptions;
+  engineOriginalAlpha: ExportEngineOptions;
+  /**
+   * Append a few digits from the image's local identifier in Photos.app, useful to avoid name collisions if exporting multiple album-worth of photos.
+   * Only applies to `FileNameOptions` `title` or `uuid`. This is NOT the same as a content hash.
+   */
+  fileNameAppendUuidFragment: boolean;
+  fileNameNormalizeExtensions: boolean;
+  fileNamePrecedence: FileNameOptions[];
+  fileNameSluggify: boolean;
+};
+type ExportApplePhotoResult = {
+  exportEngine: ExportEngine;
+  exportOptions: ExportApplePhotoOptions;
+  path: string;
+  photoInfo: PhotoInfo;
+};
+type FileNameOptions = 'fileName' | 'title' | 'uuid';
+/** Also normalizes */
+//#endregion
+//#region src/utilities/image/tags.d.ts
+declare const VALID_LABELS: readonly ["animation", "diagram", "illustration", "image", "photo", "render", "screenshot", "video"];
+type Label = (typeof VALID_LABELS)[number];
+type ValidateTagsResult = {
+  issues: string[];
+  valid: boolean;
+};
+type AphexMetadata = {
+  exportOptions: ExportOptions;
+  photoInfo: PhotoInfo;
+};
+type ImageTags = {
+  aphexMetadata?: AphexMetadata | undefined; /** Human Name */
+  creator?: string | undefined; /** Organization */
+  credit?: string | undefined; /** Description, used as alt text in HTML content */
+  description?: string | undefined;
+  /**
+  Image Type, e.g. 'animation', 'diagram', 'illustration', 'screenshot',
+  'image', 'photo', 'render', 'video'
+   */
+  label?: Label | undefined;
+  preservedFileName?: string | undefined;
+};
+//#endregion
+//#region src/pipeline/image-metadata.d.ts
+type ManageMetadataOptions = {
+  syncToEdited: boolean;
+  syncToTarget: boolean;
+  tagsToSync: Array<keyof ImageTags>;
+  validate: boolean;
+  writeAphexMetadata: boolean;
+};
+type ManageMetadataResult = {
+  photoInfo: PhotoInfo;
+  tagsToEdited: Array<keyof ImageTags> | undefined;
+  tagsToTarget: Array<keyof ImageTags> | undefined;
+  validationResult: undefined | ValidateTagsResult;
+};
+//#endregion
+//#region src/utilities/image/color.d.ts
+declare const validColorProfiles: readonly ["Adobe RGB (1998)", "Apple Wide Color Sharing Profile", "Display P3", "None", "ProPhoto RGB", "sRGB IEC61966-2.1", "Unsupported"];
+type ColorProfile = (typeof validColorProfiles)[number];
+/**
+ * Normalize the color profile of an image
+ */
+declare function normalizeColorProfile(imagePath: string, preserveColorProfiles?: ColorProfile[], defaultColorProfile?: ColorProfile): Promise<'assigned' | 'converted' | 'no-action'>;
+//#endregion
+//#region src/utilities/image/convert.d.ts
+type LosslessFormat = 'avif' | 'none' | 'png' | 'webp';
+type NearLosslessFormat = 'none' | 'webp';
+type LossyFormat = 'avif' | 'jpeg' | 'none' | 'webp';
+/**
+ * Configuration options for image compression.
+ *
+ * The compression process follows a three-tier approach:
+ * 1. First attempts lossless compression if enabled
+ * 2. Falls back to near-lossless compression if lossless exceeds size limit
+ * 3. Finally uses lossy compression if other methods fail to meet size requirements
+ *
+ * Set format to 'none' to disable that compression tier.
+ */
+type CompressImageOptions = {
+  /**
+   * Force compression even if the original image is already within the size limit.
+   * When false, images smaller than maxFileSizeBytes are copied without modification.
+   */
+  forceCompression: boolean;
+  /**
+   * Format to use for lossless compression (first attempt).
+   * - 'avif': Best compression but slower encoding
+   * - 'png': Good compatibility, optimized with oxipng
+   * - 'webp': Good balance of compression and speed
+   * - 'none': Skip lossless compression
+   */
+  losslessFormat: LosslessFormat;
+  /**
+   * Format to use for lossy compression (final fallback).
+   * - 'avif': Best compression but very slow encoding
+   * - 'jpeg': Good compatibility, uses mozjpeg encoder
+   * - 'webp': Good balance of compression and speed
+   * - 'none': Skip lossy compression (may result in oversized files)
+   */
+  lossyFormat: LossyFormat;
+  /**
+   * Quality level for lossy compression (0-1 scale).
+   * - 0: Lowest quality, smallest file size
+   * - 1: Highest quality, largest file size
+   * - Recommended range: 0.85-0.96 for high-quality images
+   */
+  lossyQuality: number;
+  /**
+   * Maximum allowed file size in bytes.
+   * Images exceeding this size will be compressed using the configured formats.
+   * The compression process stops when this target is met or all options are exhausted.
+   */
+  maxFileSizeBytes: number;
+  /**
+   * Format to use for near-lossless compression (second attempt).
+   * - 'webp': Only format currently supporting near-lossless mode
+   * - 'none': Skip near-lossless compression
+   */
+  nearLosslessFormat: NearLosslessFormat;
+};
+/**
+ * Compress an image to a target size
+ */
+declare function compressImage(sourceImagePath: string, destinationDirectory: string, options: CompressImageOptions): Promise<{
+  compression: 'lossless' | 'lossy' | 'near-lossless' | 'none';
+  path: string;
+}>;
+//#endregion
+//#region src/utilities/image/image.d.ts
+type ImageInfo = {
+  alpha: boolean;
+  colorProfile: string;
+  dimensionsPixels: {
+    width: number;
+    height: number;
+  };
+  mime: ImageMimeType;
+  path: string;
+  sizeBytes: number;
+  tags: ImageTags;
+};
+//#endregion
+//#region src/pipeline/image-process.d.ts
+type ProcessImageOptions = CompressImageOptions & {
+  /** Fallback color profile applied when source profile is not in preserve list */defaultColorProfile: ColorProfile; /** Calculate SSIM/PSNR/DSSIM metrics comparing original vs processed images */
+  logSimilarity: boolean; /** Lossless format used specifically for images with alpha channels */
+  losslessFormatAlpha: LosslessFormat; /** Lossy format used specifically for images with alpha channels */
+  lossyFormatAlpha: LossyFormat; /** Maximum pixel dimensions before triggering resize (width OR height) */
+  maxDimensionsPixels: {
+    width: number;
+    height: number;
+  }; /** Near-lossless format used specifically for images with alpha channels */
+  nearLosslessFormatAlpha: NearLosslessFormat; /** Image formats that bypass conversion and compression entirely */
+  passthroughFormats: ImageMimeType[]; /** Color profiles that are kept unchanged instead of being normalized */
+  preserveColorProfiles: ColorProfile[];
+};
+type ProcessImageResult = {
+  input: ImageInfo;
+  output: ImageInfo;
+  path: string;
+  report: {
+    color: Awaited<ReturnType<typeof normalizeColorProfile>>;
+    compression: Awaited<ReturnType<typeof compressImage>>['compression'];
+    date: Date;
+    durationMs: number;
+    similarity?: {
+      dssim: number;
+      psnr: number;
+      ssim: number;
+    };
+  };
+};
+/**
+ * Process an image
+ *
+ * Run in parallel through a worker for album processing
+ */
+declare function processImage(sourceImagePath: string, destinationDirectory: string, options: ProcessImageOptions): Promise<ProcessImageResult>;
+//#endregion
+//#region src/pipeline/image-sync.d.ts
+type DiffStrategy = 'exif-tags' | 'export-options' | 'file-name' | 'force-update' | 'metadata-options' | 'photo-info' | 'process-options';
+type SyncOptions = {
+  deleteOthers: boolean;
+  deleteTarget: boolean;
+  diffStrategies: DiffStrategy[];
+  forceUpdate: boolean;
+};
+type SyncResult = {
+  plan: Array<{
+    diffedVia: DiffStrategy | undefined;
+    matchFilePath: string | undefined;
+    photoInfo: PhotoInfo;
+    status: 'changed' | 'new' | 'unchanged';
+  }>;
+  toDelete: string[];
+};
+//#endregion
+//#region src/utilities/exiftool.d.ts
+/**
+ * End the exiftool process gracefully
+ *
+ * This should be called when you're done using exiftool to prevent
+ * hanging processes. It's safe to call multiple times.
+ */
+declare function endExiftool(): Promise<void>;
+//#endregion
+//#region src/utilities/log.d.ts
+/**
+ * Set the logger instance for the module.
+ * Export this for library consumers to inject their own logger.
+ * @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
+ */
+declare function setLogger(logger?: ILogBasic | ILogLayer<unknown>): void;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Helper for deep merging ExportOptions object against library defaults.
+ * Exported for unplugin-aphex.
+ */
+declare function mergeDefaultExportOptions(options: PartialDeep<ExportOptions> | undefined): ExportOptions;
+type ExportOptions = {
+  exportOptions: ExportApplePhotoOptions;
+  metadataOptions: 'disabled' | ManageMetadataOptions;
+  processOptions: 'disabled' | ProcessImageOptions;
+  syncOptions: 'disabled' | SyncOptions;
+};
+declare const defaultSyncOptions: SyncOptions;
+declare const defaultExportOptions: ExportOptions;
+/** Some fields omitted for relevance... */
+type ExportResults = {
+  exportResult: Simplify<Omit<ExportApplePhotoResult, 'exportOptions' | 'path' | 'photoInfo'>> | undefined;
+  metadataResult: Simplify<Omit<ManageMetadataResult, 'photoInfo'>> | undefined;
+  processResult: Simplify<OmitDeep<ProcessImageResult, 'input.path' | 'output.path' | 'path'>> | undefined;
+  syncResult: Simplify<Omit<SyncResult['plan'][number], 'photoInfo'>> | undefined;
+};
+type ExportResult = {
+  options: ExportOptions;
+  path: string;
+  photoInfo: PhotoInfo;
+  results: ExportResults;
+};
+/**
+ * Export a single photo
+ */
+declare function exportPhoto(identifier: PhotoInfo | string, destinationDirectory: string, options?: PartialDeep<ExportOptions>): Promise<ExportResult>;
+/**
+ * Export photos
+ */
+declare function exportPhotos(identifiers: Array<AlbumInfo | PhotoInfo | string>, destinationDirectory: string, options?: PartialDeep<ExportOptions>): Promise<ExportResult[]>;
+//#endregion
+export { ExportOptions, ExportResult, IMAGE_MIME_TYPES, type ImageMimeType, defaultExportOptions, defaultSyncOptions, endExiftool, exportPhoto, exportPhotos, aphexAlbumInfo as getAlbumInfo, aphexPhotoInfo as getPhotoInfo, interactiveSessionStart, interactiveSessionStop, mergeDefaultExportOptions, processImage, setLogger };