File Management

/**
 * Add source file to project with build phase integration
 * Automatically adds to PBXBuildFile, PBXFileReference, and PBXSourcesBuildPhase
 * @param {string} path - File path relative to project
 * @param {object} opt - Options including target, weak linking, compiler flags
 * @param {string} group - Group key for organization, defaults to plugin handling
 * @returns {object|boolean} File object or false if file already exists
 */
addSourceFile(path, opt, group);

/**
 * Remove source file from project and all build phases
 * @param {string} path - File path relative to project
 * @param {object} opt - Options including target specification
 * @param {string} group - Group key where file is located
 * @returns {object} Removed file object
 */
removeSourceFile(path, opt, group);

// Add Objective-C source file
const file = proj.addSourceFile('src/MyClass.m');
console.log('Added file:', file.basename);

// Add Swift file with compiler flags
const swiftFile = proj.addSourceFile('src/MySwiftClass.swift', {
    compilerFlags: '-fno-objc-arc'
});

// Add source file to specific group and target
const targetFile = proj.addSourceFile('src/TargetSpecific.m', {
    target: 'TARGET_UUID_HERE'
}, 'CustomGroup');

// Remove source file
proj.removeSourceFile('src/OldClass.m');

/**
 * Add header file to project
 * Headers are typically added to file references but not build phases
 * @param {string} path - File path relative to project
 * @param {object} opt - Options object
 * @param {string} group - Group key for organization
 * @returns {object|null} File object or null if file already exists
 */
addHeaderFile(path, opt, group);

/**
 * Remove header file from project
 * @param {string} path - File path relative to project
 * @param {object} opt - Options object
 * @param {string} group - Group key where file is located
 * @returns {object} Removed file object
 */
removeHeaderFile(path, opt, group);

// Add header file
const header = proj.addHeaderFile('src/MyClass.h');

// Add header to specific group
const groupedHeader = proj.addHeaderFile('include/PublicAPI.h', {}, 'PublicHeaders');

// Remove header file
proj.removeHeaderFile('src/OldHeader.h');

/**
 * Add plugin file to project with plugin-specific handling
 * Plugin files have special path correction and are added to the plugins group
 * @param {string} path - File path relative to project
 * @param {object} opt - Options object including target specification
 * @returns {object|null} File object or null if file already exists
 */
addPluginFile(path, opt);

/**
 * Remove plugin file from project and plugins group
 * @param {string} path - File path relative to project
 * @param {object} opt - Options object including target specification
 * @returns {object} Removed file object
 */
removePluginFile(path, opt);

// Add plugin source file
const pluginFile = proj.addPluginFile('plugins/MyPlugin/src/MyPlugin.m');

// Add plugin file to specific target
const targetPlugin = proj.addPluginFile('plugins/MyPlugin/src/TargetPlugin.m', {
    target: 'TARGET_UUID_HERE'
});

// Remove plugin file
proj.removePluginFile('plugins/OldPlugin/src/OldPlugin.m');

// Plugin files are automatically:
// - Added to PBXFileReference section
// - Added to the plugins PBXGroup
// - Given proper plugin path correction
// - Marked with plugin flag

/**
 * Add Core Data model document to project
 * Handles .xcdatamodeld bundles with multiple model versions
 * @param {string} filePath - Path to .xcdatamodeld bundle
 * @param {string} group - Group key, defaults to 'Resources'
 * @param {object} opt - Options object
 * @returns {object|null} File object or null if file already exists
 */
addDataModelDocument(filePath, group, opt);

/**
 * Add file to XCVersionGroup section for Core Data models
 * Internal method used by addDataModelDocument
 * @param {object} file - File object with models and currentModel properties
 */
addToXcVersionGroupSection(file);

// Add Core Data model
const dataModel = proj.addDataModelDocument('Models/DataModel.xcdatamodeld');

// Add to specific group
const customDataModel = proj.addDataModelDocument(
    'CustomModels/MyModel.xcdatamodeld', 
    'DataModels'
);

// Core Data models are automatically:
// - Added to XCVersionGroup section
// - Linked to individual .xcdatamodel files
// - Added to appropriate build phases
// - Configured with current model version

/**
 * Add resource file with automatic build phase integration
 * Automatically determines file type and adds to appropriate build phases
 * @param {string} path - File path relative to project
 * @param {object} opt - Options including plugin flag, target, variant group handling
 * @param {string} group - Group key for organization
 * @returns {object|boolean} File object or false if file already exists
 */
addResourceFile(path, opt, group);

/**
 * Remove resource file from project and build phases
 * @param {string} path - File path relative to project
 * @param {object} opt - Options including target specification
 * @param {string} group - Group key where file is located
 * @returns {object} Removed file object
 */
removeResourceFile(path, opt, group);

// Add image resource
const image = proj.addResourceFile('assets/icon.png');

// Add plist file
const plist = proj.addResourceFile('config/Settings.plist');

// Add resource to specific target
const targetResource = proj.addResourceFile('assets/target-icon.png', {
    target: 'TARGET_UUID_HERE'
});

// Add plugin resource
const pluginResource = proj.addResourceFile('plugins/MyPlugin.bundle', {
    plugin: true
});

// Remove resource file
proj.removeResourceFile('assets/old-icon.png');

/**
 * Add file to copy files build phase
 * Used for copying files into the app bundle or specific locations
 * @param {string} path - File path relative to project
 * @param {object} opt - Options including target specification
 * @returns {object} File object with copy phase integration
 */
addCopyfile(path, opt);

/**
 * Remove file from copy files build phase
 * @param {string} path - File path relative to project
 * @param {object} opt - Options including target specification
 * @returns {object} Removed file object
 */
removeCopyfile(path, opt);

// Add file to copy phase
const copyFile = proj.addCopyfile('resources/data.json');

// Add file to specific target's copy phase
const targetCopyFile = proj.addCopyfile('frameworks/Custom.framework', {
    target: 'TARGET_UUID_HERE'
});

// Remove from copy phase
proj.removeCopyfile('resources/old-data.json');

/**
 * Check if file already exists in project
 * @param {string} filePath - File path to check
 * @returns {object|boolean} File object if exists, false otherwise
 */
hasFile(filePath);

// Check before adding
if (!proj.hasFile('src/NewClass.m')) {
    proj.addSourceFile('src/NewClass.m');
    console.log('File added successfully');
} else {
    console.log('File already exists in project');
}

// Get existing file info
const existingFile = proj.hasFile('src/ExistingClass.m');
if (existingFile) {
    console.log('File type:', existingFile.lastKnownFileType);
    console.log('File path:', existingFile.path);
}

/**
 * Add file to specified group without build phase integration
 * @param {string} path - File path relative to project
 * @param {string} group - Group key for organization
 * @param {object} opt - Options object
 * @returns {object|null} File object or null if file already exists
 */
addFile(path, group, opt);

/**
 * Remove file from specified group
 * @param {string} path - File path relative to project
 * @param {string} group - Group key where file is located
 * @param {object} opt - Options object
 * @returns {object} Removed file object
 */
removeFile(path, group, opt);

// Add file to custom group
const file = proj.addFile('docs/README.md', 'Documentation');

// Add file with specific options
const configFile = proj.addFile('config/build.json', 'Configuration', {
    lastKnownFileType: 'text.json'
});

// Remove file from group
proj.removeFile('docs/OLD.md', 'Documentation');

/**
 * Add product file with target options
 * Used for build outputs and target products
 * @param {string} targetPath - Product file path
 * @param {object} opt - Options including target, group, explicit file type
 * @returns {object} File object representing the product
 */
addProductFile(targetPath, opt);

/**
 * Remove product file from project
 * @param {string} path - Product file path
 * @param {object} opt - Options object
 * @returns {object} Removed file object
 */
removeProductFile(path, opt);

// Add app product
const appProduct = proj.addProductFile('MyApp.app', {
    target: 'APP_TARGET_UUID',
    group: 'Products',
    explicitFileType: 'wrapper.application'
});

// Add framework product
const frameworkProduct = proj.addProductFile('MyFramework.framework', {
    target: 'FRAMEWORK_TARGET_UUID',
    explicitFileType: 'wrapper.framework'
});

// Remove product
proj.removeProductFile('OldApp.app');

/**
 * Comprehensive options for file operations
 */
interface FileOptions {
  /** Target UUID for multi-target projects */
  target?: string;
  
  /** Enable weak linking for frameworks and libraries */
  weak?: boolean;
  
  /** Custom compiler flags for source files */
  compilerFlags?: string;
  
  /** Mark as custom framework (affects path handling) */
  customFramework?: boolean;
  
  /** Embed framework in app bundle */
  embed?: boolean;
  
  /** Code sign framework on copy */
  sign?: boolean;
  
  /** Mark as plugin file (affects group placement) */
  plugin?: boolean;
  
  /** Override explicit file type */
  explicitFileType?: string;
  
  /** Override detected file type */
  lastKnownFileType?: string;
  
  /** Override source tree setting */
  sourceTree?: string;
  
  /** Override text encoding for text files */
  defaultEncoding?: number;
  
  /** Prevent adding to variant group */
  variantGroup?: boolean;
}

/**
 * File type mappings by extension
 */
const SUPPORTED_EXTENSIONS = {
  // Source files
  'm': 'sourcecode.c.objc',
  'mm': 'sourcecode.cpp.objcpp', 
  'swift': 'sourcecode.swift',
  'h': 'sourcecode.c.h',
  'hpp': 'sourcecode.cpp.h',
  
  // Resources
  'plist': 'text.plist.xml',
  'strings': 'text.plist.strings',
  'xib': 'file.xib',
  'xcassets': 'folder.assetcatalog',
  
  // Frameworks and libraries
  'framework': 'wrapper.framework',
  'dylib': 'compiled.mach-o.dylib',
  'a': 'archive.ar',
  'tbd': 'sourcecode.text-based-dylib-definition',
  
  // Applications and bundles
  'app': 'wrapper.application',
  'appex': 'wrapper.app-extension',
  'bundle': 'wrapper.plug-in',
  
  // Data models
  'xcdatamodel': 'wrapper.xcdatamodel',
  
  // Configuration
  'xcconfig': 'text.xcconfig',
  
  // Scripts
  'sh': 'text.script.sh'
};