Framework and Library Management

/**
 * Add framework to project with linking and embedding options
 * Handles system frameworks, custom frameworks, and embedded frameworks
 * @param {string} path - Framework path (e.g., 'UIKit.framework', 'Custom.framework')
 * @param {object} opt - Options including customFramework, link, embed, target, weak
 * @returns {object|boolean} File object or false if framework already exists
 */
addFramework(path, opt);

/**
 * Remove framework from project and clean up all references
 * @param {string} path - Framework path to remove
 * @param {object} opt - Options including embed flag for cleanup
 * @returns {object} Removed framework file object
 */
removeFramework(path, opt);

// Add system framework
const uikit = proj.addFramework('UIKit.framework');

// Add framework with weak linking
const optional = proj.addFramework('SomeFramework.framework', {
    weak: true
});

// Add custom framework
const custom = proj.addFramework('MyCustom.framework', {
    customFramework: true
});

// Add embedded custom framework
const embedded = proj.addFramework('ThirdParty.framework', {
    customFramework: true,
    embed: true,
    sign: true  // Code sign on copy
});

// Add framework to specific target
const targetFramework = proj.addFramework('CoreData.framework', {
    target: 'TARGET_UUID_HERE'
});

// Add framework without linking (reference only)
const reference = proj.addFramework('Reference.framework', {
    link: false
});

// Remove framework
proj.removeFramework('OldFramework.framework');

// Remove embedded framework
proj.removeFramework('EmbeddedFramework.framework', {
    embed: true
});

/**
 * Add static library with automatic linking setup
 * Automatically configures library search paths and linking
 * @param {string} path - Library path (e.g., 'libsqlite3.a', 'libMyLib.a')
 * @param {object} opt - Options including plugin flag, target specification
 * @returns {object|boolean} File object or false if library already exists
 */
addStaticLibrary(path, opt);

// Add system static library
const sqlite = proj.addStaticLibrary('libsqlite3.a');

// Add custom static library
const customLib = proj.addStaticLibrary('libMyCustomLib.a');

// Add plugin static library
const pluginLib = proj.addStaticLibrary('libPlugin.a', {
    plugin: true
});

// Add library to specific target
const targetLib = proj.addStaticLibrary('libTargetSpecific.a', {
    target: 'TARGET_UUID_HERE'
});

/**
 * Add framework search path for custom frameworks
 * @param {object} file - File object representing the framework
 */
addToFrameworkSearchPaths(file);

/**
 * Remove framework search path
 * @param {object} file - File object representing the framework
 */
removeFromFrameworkSearchPaths(file);

/**
 * Add library search path for static libraries
 * @param {object|string} file - File object or path string
 */
addToLibrarySearchPaths(file);

/**
 * Remove library search path
 * @param {object} file - File object representing the library
 */
removeFromLibrarySearchPaths(file);

/**
 * Add header search path for header files
 * @param {object|string} file - File object or path string
 */
addToHeaderSearchPaths(file);

/**
 * Remove header search path
 * @param {object} file - File object representing the header location
 */
removeFromHeaderSearchPaths(file);

// Framework search paths are automatically managed when adding custom frameworks
const customFramework = proj.addFramework('Custom.framework', {
    customFramework: true
});
// Search path automatically added

// Manually add library search path
proj.addToLibrarySearchPaths('/usr/local/lib');

// Add header search path for custom headers
proj.addToHeaderSearchPaths('$(SRCROOT)/ThirdParty/include');

// Remove search paths
proj.removeFromFrameworkSearchPaths(customFramework);
proj.removeFromLibrarySearchPaths('/usr/local/lib');

/**
 * Add other linker flag
 * Used for additional linking options like -ObjC, -all_load, etc.
 * @param {string} flag - Linker flag to add
 */
addToOtherLinkerFlags(flag);

/**
 * Remove other linker flag
 * @param {string} flag - Linker flag to remove
 */
removeFromOtherLinkerFlags(flag);

// Add common linker flags
proj.addToOtherLinkerFlags('-ObjC');
proj.addToOtherLinkerFlags('-all_load');
proj.addToOtherLinkerFlags('-force_load $(BUILT_PRODUCTS_DIR)/libCustom.a');

// Add framework-specific flags
proj.addToOtherLinkerFlags('-framework CoreGraphics');
proj.addToOtherLinkerFlags('-weak_framework SomeOptionalFramework');

// Remove linker flags
proj.removeFromOtherLinkerFlags('-all_load');

/**
 * Options for framework operations
 */
interface FrameworkOptions {
  /** Target UUID for multi-target projects */
  target?: string;
  
  /** Mark as custom framework (not system framework) */
  customFramework?: boolean;
  
  /** Enable framework linking (default: true) */
  link?: boolean;
  
  /** Embed framework in app bundle */
  embed?: boolean;
  
  /** Enable weak linking for optional frameworks */
  weak?: boolean;
  
  /** Code sign framework when copying */
  sign?: boolean;
}

/**
 * Framework type detection and handling
 */
interface FrameworkHandling {
  /** System frameworks (UIKit.framework, Foundation.framework) */
  system: {
    sourceTree: 'SDKROOT',
    path: 'System/Library/Frameworks/',
    searchPaths: false  // No custom search paths needed
  };
  
  /** Custom frameworks (MyFramework.framework) */
  custom: {
    sourceTree: '"<group>"',
    path: 'relative to project',
    searchPaths: true,  // Automatically adds search paths
    embedding: 'optional'  // Can be embedded in app bundle
  };
  
  /** Embedded frameworks (for app extensions, etc.) */
  embedded: {
    copyPhase: 'PBXCopyFilesBuildPhase',
    destination: 'frameworks',
    codeSign: 'optional'  // Can be code signed on copy
  };
}

// iOS system frameworks
proj.addFramework('UIKit.framework');
proj.addFramework('Foundation.framework');
proj.addFramework('CoreData.framework');

// Optional system frameworks
proj.addFramework('HealthKit.framework', { weak: true });

// Local custom framework
proj.addFramework('MySDK.framework', {
    customFramework: true
});

// Embedded custom framework with code signing
proj.addFramework('ThirdPartySDK.framework', {
    customFramework: true,
    embed: true,
    sign: true
});

// System libraries
proj.addStaticLibrary('libz.a');
proj.addStaticLibrary('libsqlite3.a');

// Custom libraries with search paths
proj.addStaticLibrary('libMyLib.a');
proj.addToLibrarySearchPaths('$(SRCROOT)/Libraries');

// System dynamic libraries (treated as frameworks)
proj.addFramework('libxml2.dylib');

// Custom dynamic libraries
proj.addFramework('libCustom.dylib', {
    customFramework: true
});

// Add .tbd file (iOS 9+ text-based dylib definitions)
proj.addFramework('libSystem.tbd');

// Custom .tbd file
proj.addFramework('MyLib.tbd', {
    customFramework: true
});

// App extension with embedded framework
const framework = proj.addFramework('SharedFramework.framework', {
    customFramework: true,
    embed: true,
    target: 'APP_EXTENSION_TARGET_UUID'
});

// The framework is automatically:
// 1. Added to file references
// 2. Added to framework group
// 3. Added to frameworks build phase
// 4. Added to embed frameworks build phase
// 5. Configured for code signing if requested