Sf Metadata

# Claude Code lifecycle hooks for sf-metadata
# These hooks are registered by the installer (tools/install.py)
# and are NOT part of the Agent Skills open specification.

PreToolUse:
- matcher: Bash
  hooks:
  - type: command
    command: "python3 ${SHARED_HOOKS}/scripts/guardrails.py"
    timeout: 5000
PostToolUse:
- matcher: Write
  hooks:
  - type: command
    command: "python3 ${SKILL_HOOKS}/post-write-validate.py"
    timeout: 10000

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Checkbox Field Template

    Usage: Boolean true/false values

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Is_Active__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Is Active")
    - {{DEFAULT_VALUE}} - true or false (required for checkboxes)
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - Checkboxes are never required (always have a value)
    - Default value is mandatory
    - Good for flags, toggles, opt-ins
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Checkbox</type>
    <defaultValue>{{DEFAULT_VALUE}}</defaultValue>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Currency Field Template

    Usage: Monetary values (respects org currency settings)

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Total_Amount__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Total Amount")
    - {{PRECISION}} - Total digits (1-18)
    - {{SCALE}} - Decimal places (0-17, typically 2 for currency)
    - {{REQUIRED}} - true or false
    - {{DEFAULT_VALUE}} - Optional default (e.g., "0.00")
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - Automatically displays with org's currency symbol
    - In multi-currency orgs, stores in corporate currency
    - Use precision=18, scale=2 for standard currency
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Currency</type>
    <precision>{{PRECISION}}</precision>
    <scale>{{SCALE}}</scale>
    <required>{{REQUIRED}}</required>
    <defaultValue>{{DEFAULT_VALUE}}</defaultValue>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Date Field Template

    Usage: Calendar dates (without time component)

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Due_Date__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Due Date")
    - {{REQUIRED}} - true or false
    - {{DEFAULT_VALUE}} - Optional default (use formula like TODAY())
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - For DateTime fields, use type "DateTime" instead
    - Default value can use formulas: TODAY(), TODAY() + 30
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Date</type>
    <required>{{REQUIRED}}</required>
    <defaultValue>{{DEFAULT_VALUE}}</defaultValue>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Email Field Template

    Usage: Email addresses with format validation

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Work_Email__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Work Email")
    - {{REQUIRED}} - true or false
    - {{UNIQUE}} - true or false
    - {{EXTERNAL_ID}} - true or false
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - Automatically validates email format
    - Max 80 characters
    - Clickable in Lightning (opens email client)
    - Use for any email address field beyond standard Email
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Email</type>
    <required>{{REQUIRED}}</required>
    <unique>{{UNIQUE}}</unique>
    <externalId>{{EXTERNAL_ID}}</externalId>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Formula Field Template

    Usage: Calculated field based on other fields

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Full_Name__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Full Name")
    - {{FORMULA_RETURN_TYPE}} - Text, Number, Currency, Date, DateTime, Checkbox
    - {{FORMULA}} - The formula expression
    - {{PRECISION}} - Total digits (for Number/Currency/Percent)
    - {{SCALE}} - Decimal places (for Number/Currency/Percent)
    - {{BLANK_AS_ZERO}} - true (treat blank as zero) or false (treat as blank)
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Return Type Options:
    - Text: Returns string value
    - Number: Returns numeric value
    - Currency: Returns monetary value
    - Percent: Returns percentage (0-100 stored, displayed with %)
    - Date: Returns date value
    - DateTime: Returns date/time value
    - Checkbox: Returns true/false

    Notes:
    - Formula fields are read-only
    - Counted against formula character limit (5,000 compiled)
    - Can reference fields up to 10 relationships away
    - Use TEXT() for picklist values in formulas
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>{{FORMULA_RETURN_TYPE}}</type>
    <!-- Include precision/scale for Number, Currency, Percent types -->
    <precision>{{PRECISION}}</precision>
    <scale>{{SCALE}}</scale>
    <formula>{{FORMULA}}</formula>
    <formulaTreatBlanksAs>{{BLANK_AS_ZERO}}</formulaTreatBlanksAs>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<!--
    Common Formula Examples:

    Text concatenation:
    FirstName__c & " " & LastName__c

    Conditional (IF):
    IF(Amount__c > 100000, "Large", IF(Amount__c > 10000, "Medium", "Small"))

    Date calculation:
    TODAY() - CreatedDate

    Picklist reference:
    TEXT(Status__c)

    Cross-object reference:
    Account.Industry

    NULL handling:
    BLANKVALUE(Phone__c, "No Phone")

    CASE statement:
    CASE(Status__c,
        "New", 1,
        "In Progress", 2,
        "Completed", 3,
        0)
-->

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Lookup Field Template

    Usage: Optional relationship to another object

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Primary_Contact__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Primary Contact")
    - {{RELATED_OBJECT}} - Object to relate to (e.g., "Contact")
    - {{RELATIONSHIP_LABEL}} - Label on related list (e.g., "Related Accounts")
    - {{RELATIONSHIP_NAME}} - API name for relationship (e.g., "Related_Accounts")
    - {{REQUIRED}} - true or false
    - {{DELETE_CONSTRAINT}} - SetNull, Restrict, or blank
    - {{LOOKUP_FILTER}} - Optional filter criteria (XML block)
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Delete Constraint Options:
    - (blank): Clear the value (default)
    - SetNull: Set to null when parent deleted
    - Restrict: Prevent deletion if children exist

    Notes:
    - For required parent relationships, use Master-Detail instead
    - Lookup relationships don't support roll-up summaries
    - Child records are NOT deleted when parent is deleted
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Lookup</type>
    <referenceTo>{{RELATED_OBJECT}}</referenceTo>
    <relationshipLabel>{{RELATIONSHIP_LABEL}}</relationshipLabel>
    <relationshipName>{{RELATIONSHIP_NAME}}</relationshipName>
    <required>{{REQUIRED}}</required>
    <deleteConstraint>{{DELETE_CONSTRAINT}}</deleteConstraint>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
    <!--
    Optional: Lookup Filter
    <lookupFilter>
        <active>true</active>
        <booleanFilter>1</booleanFilter>
        <filterItems>
            <field>{{RELATED_OBJECT}}.IsActive__c</field>
            <operation>equals</operation>
            <value>true</value>
        </filterItems>
        <isOptional>false</isOptional>
    </lookupFilter>
    -->
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Master-Detail Field Template

    Usage: Required parent relationship with cascade delete

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Account__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Account")
    - {{RELATED_OBJECT}} - Parent object (e.g., "Account")
    - {{RELATIONSHIP_LABEL}} - Label on related list (e.g., "Line Items")
    - {{RELATIONSHIP_NAME}} - API name for relationship (e.g., "Line_Items")
    - {{RELATIONSHIP_ORDER}} - 0 for primary, 1 for secondary M-D
    - {{REPARENTABLE}} - true or false (allow changing parent)
    - {{WRITE_REQUIRES_MASTER}} - true or false
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - Child records are deleted when parent is deleted
    - Supports roll-up summary fields on parent
    - Child sharing is controlled by parent (ControlledByParent)
    - Cannot be converted to Lookup after creation
    - Maximum 2 Master-Detail fields per object
    - First M-D determines the primary parent for sharing
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>MasterDetail</type>
    <referenceTo>{{RELATED_OBJECT}}</referenceTo>
    <relationshipLabel>{{RELATIONSHIP_LABEL}}</relationshipLabel>
    <relationshipName>{{RELATIONSHIP_NAME}}</relationshipName>
    <relationshipOrder>{{RELATIONSHIP_ORDER}}</relationshipOrder>
    <reparentableMasterDetail>{{REPARENTABLE}}</reparentableMasterDetail>
    <writeRequiresMasterRead>{{WRITE_REQUIRES_MASTER}}</writeRequiresMasterRead>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Multi-Select Picklist Field Template

    Usage: Multiple-select dropdown with predefined values

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Categories__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Categories")
    - {{VISIBLE_LINES}} - Number of visible lines (3-10)
    - {{REQUIRED}} - true or false
    - {{RESTRICTED}} - true (only defined values) or false
    - {{SORTED}} - true (alphabetical) or false (maintain order)
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - Values stored as semicolon-separated string
    - Use INCLUDES() function in formulas to check values
    - Cannot be used in roll-up summaries or unique constraints
    - Maximum 500 values
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>MultiselectPicklist</type>
    <visibleLines>{{VISIBLE_LINES}}</visibleLines>
    <required>{{REQUIRED}}</required>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
    <valueSet>
        <restricted>{{RESTRICTED}}</restricted>
        <valueSetDefinition>
            <sorted>{{SORTED}}</sorted>
            <!-- Example values - replace with actual values -->
            <value>
                <fullName>Category_A</fullName>
                <default>false</default>
                <label>Category A</label>
            </value>
            <value>
                <fullName>Category_B</fullName>
                <default>false</default>
                <label>Category B</label>
            </value>
            <value>
                <fullName>Category_C</fullName>
                <default>false</default>
                <label>Category C</label>
            </value>
        </valueSetDefinition>
    </valueSet>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Number Field Template

    Usage: Numeric values (integers or decimals)

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Quantity__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Quantity")
    - {{PRECISION}} - Total digits (1-18)
    - {{SCALE}} - Decimal places (0-17, must be less than precision)
    - {{REQUIRED}} - true or false
    - {{UNIQUE}} - true or false
    - {{EXTERNAL_ID}} - true or false
    - {{DEFAULT_VALUE}} - Optional default (e.g., "0")
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Examples:
    - Integer: precision=18, scale=0
    - Decimal (2 places): precision=18, scale=2
    - Percentage: precision=5, scale=2 (stores as decimal, displays as %)
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Number</type>
    <precision>{{PRECISION}}</precision>
    <scale>{{SCALE}}</scale>
    <required>{{REQUIRED}}</required>
    <unique>{{UNIQUE}}</unique>
    <externalId>{{EXTERNAL_ID}}</externalId>
    <defaultValue>{{DEFAULT_VALUE}}</defaultValue>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Phone Field Template

    Usage: Phone numbers with click-to-dial support

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Mobile_Phone__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Mobile Phone")
    - {{REQUIRED}} - true or false
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - Max 40 characters
    - Supports click-to-dial in Lightning (with telephony integration)
    - No automatic format validation (use validation rule if needed)
    - Consider using libphonenumber for advanced validation
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Phone</type>
    <required>{{REQUIRED}}</required>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Picklist Field Template

    Usage: Single-select dropdown with predefined values

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Status__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Status")
    - {{REQUIRED}} - true or false
    - {{RESTRICTED}} - true (only defined values) or false (allows new values)
    - {{SORTED}} - true (alphabetical) or false (maintain order)
    - {{PICKLIST_VALUES}} - Replace entire section with value elements
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - For reusable picklists across objects, use Global Value Sets instead
    - Restricted picklists prevent data quality issues
    - Consider validation rules for complex dependencies
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Picklist</type>
    <required>{{REQUIRED}}</required>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
    <valueSet>
        <restricted>{{RESTRICTED}}</restricted>
        <valueSetDefinition>
            <sorted>{{SORTED}}</sorted>
            <!-- Example values - replace with actual values -->
            <value>
                <fullName>New</fullName>
                <default>true</default>
                <label>New</label>
            </value>
            <value>
                <fullName>In_Progress</fullName>
                <default>false</default>
                <label>In Progress</label>
            </value>
            <value>
                <fullName>Completed</fullName>
                <default>false</default>
                <label>Completed</label>
            </value>
            <value>
                <fullName>Cancelled</fullName>
                <default>false</default>
                <label>Cancelled</label>
            </value>
        </valueSetDefinition>
    </valueSet>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Roll-Up Summary Field Template

    Usage: Aggregate child records (only on Master-Detail parent)

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Total_Amount__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Total Amount")
    - {{SUMMARIZED_OBJECT}} - Child object API name (e.g., "Line_Item__c")
    - {{SUMMARY_TYPE}} - SUM, COUNT, MIN, or MAX
    - {{SUMMARIZED_FIELD}} - Field to aggregate (for SUM, MIN, MAX)
    - {{FILTER_CRITERIA}} - Optional filter (XML block)
    - {{PRECISION}} - Total digits (for currency/number results)
    - {{SCALE}} - Decimal places
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Summary Type Options:
    - COUNT: Count of child records (no field needed)
    - SUM: Sum of numeric field values
    - MIN: Minimum value
    - MAX: Maximum value

    Notes:
    - Only available on Master-Detail parent objects
    - Cannot summarize formula fields (except cross-object formulas)
    - Cannot summarize Long Text Area or Multi-Select Picklist
    - For Lookup relationships, use DLRS or trigger-based calculation
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Summary</type>
    <summarizedField>{{SUMMARIZED_OBJECT}}.{{SUMMARIZED_FIELD}}</summarizedField>
    <summaryForeignKey>{{SUMMARIZED_OBJECT}}.{{MASTER_DETAIL_FIELD}}</summaryForeignKey>
    <summaryOperation>{{SUMMARY_TYPE}}</summaryOperation>
    <!-- Include precision/scale for SUM, MIN, MAX on numeric fields -->
    <precision>{{PRECISION}}</precision>
    <scale>{{SCALE}}</scale>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
    <!--
    Optional: Filter criteria (only aggregate records matching criteria)
    <summaryFilterItems>
        <field>{{SUMMARIZED_OBJECT}}.Status__c</field>
        <operation>equals</operation>
        <value>Completed</value>
    </summaryFilterItems>
    -->
</CustomField>

<!--
    Examples:

    COUNT all line items:
    <summaryOperation>count</summaryOperation>
    (no summarizedField needed)

    SUM of Amount:
    <summaryOperation>sum</summaryOperation>
    <summarizedField>Line_Item__c.Amount__c</summarizedField>

    MAX Close Date:
    <summaryOperation>max</summaryOperation>
    <summarizedField>Opportunity__c.CloseDate</summarizedField>

    With Filter (only Won opportunities):
    <summaryFilterItems>
        <field>Opportunity__c.StageName</field>
        <operation>equals</operation>
        <value>Closed Won</value>
    </summaryFilterItems>
-->

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Text Field Template

    Usage: Short text fields up to 255 characters

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Account_Code__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Account Code")
    - {{LENGTH}} - Maximum characters (1-255)
    - {{REQUIRED}} - true or false
    - {{UNIQUE}} - true or false (case-insensitive by default)
    - {{EXTERNAL_ID}} - true or false (for integration)
    - {{DEFAULT_VALUE}} - Optional default value
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Text</type>
    <length>{{LENGTH}}</length>
    <required>{{REQUIRED}}</required>
    <unique>{{UNIQUE}}</unique>
    <caseSensitive>false</caseSensitive>
    <externalId>{{EXTERNAL_ID}}</externalId>
    <defaultValue>{{DEFAULT_VALUE}}</defaultValue>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Long Text Area Field Template

    Usage: Multi-line text fields for descriptions, notes, etc.

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Description__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Description")
    - {{LENGTH}} - Maximum characters (up to 131,072)
    - {{VISIBLE_LINES}} - Display lines in UI (2-50)
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - Cannot be unique or external ID
    - Cannot be used in filters, roll-ups, or formulas
    - For rich text with formatting, use Rich Text Area instead
    - Consider character limits for API and report constraints
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>LongTextArea</type>
    <length>{{LENGTH}}</length>
    <visibleLines>{{VISIBLE_LINES}}</visibleLines>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    URL Field Template

    Usage: Web addresses with clickable links

    Placeholders:
    - {{FIELD_API_NAME}} - API name ending in __c (e.g., "Website__c")
    - {{FIELD_LABEL}} - User-friendly label (e.g., "Website")
    - {{REQUIRED}} - true or false
    - {{DESCRIPTION}} - Field purpose
    - {{HELP_TEXT}} - Inline help for users

    Notes:
    - Max 255 characters
    - Automatically renders as clickable link
    - Should include protocol (https://)
    - Opens in new tab when clicked
-->
<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{FIELD_API_NAME}}</fullName>
    <label>{{FIELD_LABEL}}</label>
    <type>Url</type>
    <required>{{REQUIRED}}</required>
    <description>{{DESCRIPTION}}</description>
    <inlineHelpText>{{HELP_TEXT}}</inlineHelpText>
    <trackHistory>false</trackHistory>
    <trackTrending>false</trackTrending>
</CustomField>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Page Layout Template

    Usage: Define field arrangement and sections for record pages

    Placeholders:
    - {{LAYOUT_NAME}} - Full name (Object-Layout Name, e.g., "Account-Business Account Layout")

    Notes:
    - Page layouts are complex XML structures
    - Consider using Lightning Record Pages instead for modern UIs
    - Layout determines:
      - Field arrangement in sections
      - Related lists
      - Actions/buttons
      - Canvas apps, Visualforce pages
-->
<Layout xmlns="http://soap.sforce.com/2006/04/metadata">
    <!--
    ═══════════════════════════════════════════
    LAYOUT SECTIONS
    ═══════════════════════════════════════════
    -->
    <layoutSections>
        <customLabel>false</customLabel>
        <detailHeading>false</detailHeading>
        <editHeading>true</editHeading>
        <label>Information</label>
        <layoutColumns>
            <layoutItems>
                <behavior>Required</behavior>
                <field>Name</field>
            </layoutItems>
            <layoutItems>
                <behavior>Edit</behavior>
                <field>Type</field>
            </layoutItems>
        </layoutColumns>
        <layoutColumns>
            <layoutItems>
                <behavior>Edit</behavior>
                <field>OwnerId</field>
            </layoutItems>
        </layoutColumns>
        <style>TwoColumnsTopToBottom</style>
    </layoutSections>

    <layoutSections>
        <customLabel>true</customLabel>
        <detailHeading>true</detailHeading>
        <editHeading>true</editHeading>
        <label>Additional Information</label>
        <layoutColumns>
            <layoutItems>
                <behavior>Edit</behavior>
                <field>Description</field>
            </layoutItems>
        </layoutColumns>
        <layoutColumns/>
        <style>TwoColumnsLeftToRight</style>
    </layoutSections>

    <layoutSections>
        <customLabel>true</customLabel>
        <detailHeading>true</detailHeading>
        <editHeading>true</editHeading>
        <label>System Information</label>
        <layoutColumns>
            <layoutItems>
                <behavior>Readonly</behavior>
                <field>CreatedById</field>
            </layoutItems>
        </layoutColumns>
        <layoutColumns>
            <layoutItems>
                <behavior>Readonly</behavior>
                <field>LastModifiedById</field>
            </layoutItems>
        </layoutColumns>
        <style>TwoColumnsLeftToRight</style>
    </layoutSections>

    <!--
    ═══════════════════════════════════════════
    RELATED LISTS
    ═══════════════════════════════════════════
    -->
    <relatedLists>
        <fields>FULL_NAME</fields>
        <fields>CONTACT.TITLE</fields>
        <fields>CONTACT.EMAIL</fields>
        <fields>CONTACT.PHONE1</fields>
        <relatedList>RelatedContactList</relatedList>
    </relatedLists>

    <relatedLists>
        <fields>OPPORTUNITY.NAME</fields>
        <fields>OPPORTUNITY.STAGE_NAME</fields>
        <fields>OPPORTUNITY.AMOUNT</fields>
        <fields>OPPORTUNITY.CLOSE_DATE</fields>
        <relatedList>RelatedOpportunityList</relatedList>
    </relatedLists>

    <!--
    ═══════════════════════════════════════════
    QUICK ACTIONS
    ═══════════════════════════════════════════
    -->
    <quickActionList>
        <quickActionListItems>
            <quickActionName>FeedItem.TextPost</quickActionName>
        </quickActionListItems>
        <quickActionListItems>
            <quickActionName>NewTask</quickActionName>
        </quickActionListItems>
        <quickActionListItems>
            <quickActionName>NewEvent</quickActionName>
        </quickActionListItems>
        <quickActionListItems>
            <quickActionName>LogACall</quickActionName>
        </quickActionListItems>
    </quickActionList>

    <!--
    ═══════════════════════════════════════════
    DISPLAY OPTIONS
    ═══════════════════════════════════════════
    -->
    <showEmailCheckbox>false</showEmailCheckbox>
    <showHighlightsPanel>false</showHighlightsPanel>
    <showInteractionLogPanel>false</showInteractionLogPanel>
    <showRunAssignmentRulesCheckbox>false</showRunAssignmentRulesCheckbox>
    <showSubmitAndAttachButton>false</showSubmitAndAttachButton>
</Layout>

<!--
    LAYOUT BEHAVIOR OPTIONS
    ════════════════════════════════════════════

    Field behaviors:
    - Required: Field must have value (red bar)
    - Edit: Field is editable
    - Readonly: Field is read-only
    - Hidden: Field not shown (rare in layout)

    Section styles:
    - TwoColumnsTopToBottom
    - TwoColumnsLeftToRight
    - OneColumn
    - CustomLinks


    PAGE LAYOUT VS LIGHTNING RECORD PAGE
    ════════════════════════════════════════════

    Page Layout (Classic + Lightning):
    ├── Controls field arrangement
    ├── Controls related lists
    ├── Works in Classic and Lightning
    └── Assigned via Profile

    Lightning Record Page (Lightning only):
    ├── Drag-and-drop App Builder
    ├── Controls page structure
    ├── Supports components, tabs, accordions
    └── More flexible than page layouts

    RECOMMENDATION: Use Lightning Record Pages for modern UIs,
    Page Layouts for field organization and related lists.


    FILE NAMING
    ════════════════════════════════════════════

    Location: force-app/main/default/layouts/
    Format: [ObjectName]-[Layout Name].layout-meta.xml

    Examples:
    - Account-Account Layout.layout-meta.xml
    - Account-Business Account Layout.layout-meta.xml
    - Custom_Object__c-Custom Object Layout.layout-meta.xml
-->

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Custom Object Template

    Usage: Copy and customize for new custom objects

    Placeholders:
    - {{OBJECT_LABEL}} - User-friendly name (e.g., "Invoice")
    - {{OBJECT_PLURAL_LABEL}} - Plural form (e.g., "Invoices")
    - {{OBJECT_DESCRIPTION}} - Purpose of the object
    - {{NAME_FIELD_LABEL}} - Label for Name field (e.g., "Invoice Number")
    - {{NAME_FIELD_TYPE}} - Text or AutoNumber
    - {{AUTO_NUMBER_FORMAT}} - Format if AutoNumber (e.g., "INV-{0000}")
    - {{SHARING_MODEL}} - Private, ReadWrite, Read, ControlledByParent
-->
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
    <!-- Object Identity -->
    <label>{{OBJECT_LABEL}}</label>
    <pluralLabel>{{OBJECT_PLURAL_LABEL}}</pluralLabel>
    <description>{{OBJECT_DESCRIPTION}}</description>

    <!-- Name Field Configuration -->
    <nameField>
        <label>{{NAME_FIELD_LABEL}}</label>
        <type>{{NAME_FIELD_TYPE}}</type>
        <!-- Include displayFormat only for AutoNumber type -->
        <displayFormat>{{AUTO_NUMBER_FORMAT}}</displayFormat>
        <trackHistory>false</trackHistory>
    </nameField>

    <!-- Deployment Configuration -->
    <deploymentStatus>Deployed</deploymentStatus>

    <!-- Sharing & Security -->
    <sharingModel>{{SHARING_MODEL}}</sharingModel>
    <!--
        Sharing Model Options:
        - Private: Only owner and users above in role hierarchy
        - ReadWrite: All users can read and edit
        - Read: All users can read, owner can edit
        - ControlledByParent: For Master-Detail relationships
    -->

    <!-- Feature Toggles -->
    <enableHistory>true</enableHistory>
    <enableActivities>true</enableActivities>
    <enableReports>true</enableReports>
    <enableSearch>true</enableSearch>
    <enableFeeds>false</enableFeeds>
    <enableBulkApi>true</enableBulkApi>
    <enableSharing>true</enableSharing>
    <enableStreamingApi>true</enableStreamingApi>

    <!-- Search Configuration -->
    <searchLayouts>
        <customTabListAdditionalFields>Name</customTabListAdditionalFields>
        <lookupDialogsAdditionalFields>Name</lookupDialogsAdditionalFields>
        <lookupPhoneDialogsAdditionalFields>Name</lookupPhoneDialogsAdditionalFields>
        <searchResultsAdditionalFields>Name</searchResultsAdditionalFields>
    </searchLayouts>

    <!-- Compact Layout -->
    <compactLayoutAssignment>SYSTEM</compactLayoutAssignment>
</CustomObject>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Permission Set Template

    Usage: Granular permissions assigned to users on top of their profile

    BEST PRACTICE: Use Permission Sets for feature-based access control.
    Organize by feature or function, not by user role.

    Placeholders:
    - {{PERMISSION_SET_NAME}} - API name (e.g., "Invoice_Manager")
    - {{LABEL}} - User-friendly name (e.g., "Invoice Manager")
    - {{DESCRIPTION}} - Purpose of this permission set
    - {{LICENSE}} - Optional: specific license required
    - {{REQUIRES_ACTIVATION}} - true for session-based permissions

    Naming Convention:
    - Feature-based: "Invoice_Manager", "Report_Builder"
    - Integration: "Integration_API_Access"
    - Admin: "Admin_User_Management"
-->
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>{{LABEL}}</label>
    <description>{{DESCRIPTION}}</description>
    <hasActivationRequired>{{REQUIRES_ACTIVATION}}</hasActivationRequired>
    <!-- Optional: Restrict to specific license -->
    <!-- <license>{{LICENSE}}</license> -->

    <!--
    ═══════════════════════════════════════════
    OBJECT PERMISSIONS
    ═══════════════════════════════════════════
    Grant CRUD access for objects
    -->
    <objectPermissions>
        <allowCreate>true</allowCreate>
        <allowDelete>false</allowDelete>
        <allowEdit>true</allowEdit>
        <allowRead>true</allowRead>
        <modifyAllRecords>false</modifyAllRecords>
        <object>Custom_Object__c</object>
        <viewAllRecords>false</viewAllRecords>
    </objectPermissions>

    <!--
    ═══════════════════════════════════════════
    FIELD PERMISSIONS (FLS)
    ═══════════════════════════════════════════
    Grant read/edit access for specific fields
    -->
    <fieldPermissions>
        <editable>true</editable>
        <field>Custom_Object__c.Sensitive_Field__c</field>
        <readable>true</readable>
    </fieldPermissions>

    <fieldPermissions>
        <editable>false</editable>
        <field>Custom_Object__c.Read_Only_Field__c</field>
        <readable>true</readable>
    </fieldPermissions>

    <!--
    ═══════════════════════════════════════════
    TAB SETTINGS
    ═══════════════════════════════════════════
    Available, None, or Visible
    -->
    <tabSettings>
        <tab>Custom_Object__c</tab>
        <visibility>Visible</visibility>
    </tabSettings>

    <!--
    ═══════════════════════════════════════════
    RECORD TYPE ASSIGNMENTS
    ═══════════════════════════════════════════
    Make record types visible to users with this permission set
    -->
    <!--
    <recordTypeVisibilities>
        <recordType>Custom_Object__c.Record_Type_Name</recordType>
        <visible>true</visible>
    </recordTypeVisibilities>
    -->

    <!--
    ═══════════════════════════════════════════
    USER PERMISSIONS (SYSTEM PERMISSIONS)
    ═══════════════════════════════════════════
    Enable specific system-level permissions
    -->
    <!--
    <userPermissions>
        <enabled>true</enabled>
        <name>ApiEnabled</name>
    </userPermissions>
    -->

    <!--
    ═══════════════════════════════════════════
    APEX CLASS ACCESS
    ═══════════════════════════════════════════
    Grant access to Apex classes (for Visualforce, Lightning)
    -->
    <!--
    <classAccesses>
        <apexClass>MyApexController</apexClass>
        <enabled>true</enabled>
    </classAccesses>
    -->

    <!--
    ═══════════════════════════════════════════
    CUSTOM PERMISSIONS
    ═══════════════════════════════════════════
    Enable custom permissions (for feature flags)
    -->
    <!--
    <customPermissions>
        <enabled>true</enabled>
        <name>Feature_Flag_Name</name>
    </customPermissions>
    -->
</PermissionSet>

<!--
    PERMISSION SET ORGANIZATION PATTERNS
    ════════════════════════════════════════════

    1. Feature-Based (RECOMMENDED):
       - "Sales_Forecasting_Access"
       - "Marketing_Campaign_Manager"
       - "Customer_Support_Tools"

    2. Integration-Based:
       - "ERP_Integration_API"
       - "Marketing_Automation_Sync"

    3. Object-Based:
       - "Invoice_Full_Access"
       - "Contact_Read_Only"

    4. Environment/Session-Based:
       - "Elevated_Admin_Session" (requires activation)
       - "After_Hours_Access"

    PERMISSION SET GROUPS:
    Combine multiple permission sets into a single assignable group:
    - "Sales_Rep_Standard" = Sales_Forecasting + Account_Access + Report_Viewer
-->

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Profile Template

    Usage: User profile defining permissions and access

    RECOMMENDATION: Use Permission Sets instead of Profiles for granular permissions.
    Profiles should define base access; Permission Sets for feature-specific access.

    Placeholders:
    - {{PROFILE_NAME}} - Profile API name
    - {{DESCRIPTION}} - Profile purpose
    - {{USER_LICENSE}} - License type (Salesforce, Salesforce Platform, etc.)
    - {{IS_CUSTOM}} - true for custom profiles, false for standard

    Notes:
    - Standard profiles cannot be deleted
    - Profile determines record types, page layouts, and login hours
    - Field permissions and object permissions are typically managed here
    - Consider using Permission Set Groups for complex permission models
-->
<Profile xmlns="http://soap.sforce.com/2006/04/metadata">
    <custom>{{IS_CUSTOM}}</custom>
    <description>{{DESCRIPTION}}</description>
    <userLicense>{{USER_LICENSE}}</userLicense>

    <!--
    ═══════════════════════════════════════════
    OBJECT PERMISSIONS
    ═══════════════════════════════════════════
    Define CRUD access for each object
    -->
    <objectPermissions>
        <allowCreate>true</allowCreate>
        <allowDelete>false</allowDelete>
        <allowEdit>true</allowEdit>
        <allowRead>true</allowRead>
        <modifyAllRecords>false</modifyAllRecords>
        <object>Account</object>
        <viewAllRecords>false</viewAllRecords>
    </objectPermissions>

    <!-- Add more object permissions as needed -->
    <!--
    <objectPermissions>
        <allowCreate>true</allowCreate>
        <allowDelete>false</allowDelete>
        <allowEdit>true</allowEdit>
        <allowRead>true</allowRead>
        <modifyAllRecords>false</modifyAllRecords>
        <object>Custom_Object__c</object>
        <viewAllRecords>false</viewAllRecords>
    </objectPermissions>
    -->

    <!--
    ═══════════════════════════════════════════
    FIELD PERMISSIONS (FLS)
    ═══════════════════════════════════════════
    Define read/edit access for specific fields
    -->
    <fieldPermissions>
        <editable>true</editable>
        <field>Account.Industry</field>
        <readable>true</readable>
    </fieldPermissions>

    <!-- Add more field permissions as needed -->
    <!--
    <fieldPermissions>
        <editable>false</editable>
        <field>Account.Sensitive_Field__c</field>
        <readable>true</readable>
    </fieldPermissions>
    -->

    <!--
    ═══════════════════════════════════════════
    TAB VISIBILITY
    ═══════════════════════════════════════════
    DefaultOn, DefaultOff, or Hidden
    -->
    <tabVisibilities>
        <tab>standard-Account</tab>
        <visibility>DefaultOn</visibility>
    </tabVisibilities>

    <!--
    ═══════════════════════════════════════════
    RECORD TYPE ASSIGNMENTS
    ═══════════════════════════════════════════
    Assign available record types
    -->
    <!--
    <recordTypeVisibilities>
        <default>true</default>
        <recordType>Account.Business_Account</recordType>
        <visible>true</visible>
    </recordTypeVisibilities>
    -->

    <!--
    ═══════════════════════════════════════════
    PAGE LAYOUT ASSIGNMENTS
    ═══════════════════════════════════════════
    Map record types to page layouts
    -->
    <!--
    <layoutAssignments>
        <layout>Account-Account Layout</layout>
    </layoutAssignments>
    -->

    <!--
    ═══════════════════════════════════════════
    APPLICATION VISIBILITY
    ═══════════════════════════════════════════
    -->
    <applicationVisibilities>
        <application>standard__LightningSales</application>
        <default>true</default>
        <visible>true</visible>
    </applicationVisibilities>

    <!--
    ═══════════════════════════════════════════
    USER PERMISSIONS (SYSTEM PERMISSIONS)
    ═══════════════════════════════════════════
    Enable specific system permissions
    -->
    <userPermissions>
        <enabled>true</enabled>
        <name>ViewSetup</name>
    </userPermissions>
</Profile>

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Record Type Template

    Usage: Create record types to segment data and customize processes

    Placeholders:
    - {{RECORD_TYPE_API_NAME}} - API name (e.g., "Business_Account")
    - {{LABEL}} - User-friendly name (e.g., "Business Account")
    - {{ACTIVE}} - true or false
    - {{DESCRIPTION}} - Purpose of this record type
    - {{BUSINESS_PROCESS}} - Associated process (for Opportunity, Lead, Case)

    Notes:
    - Record types control picklist values, page layouts, and business processes
    - Each record type can have different page layouts per profile
    - Use sparingly - too many record types increases complexity
-->
<RecordType xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{RECORD_TYPE_API_NAME}}</fullName>
    <active>{{ACTIVE}}</active>
    <label>{{LABEL}}</label>
    <description>{{DESCRIPTION}}</description>
    <!-- Optional: Business Process (for Lead, Opportunity, Case) -->
    <!-- <businessProcess>{{BUSINESS_PROCESS}}</businessProcess> -->

    <!--
    ═══════════════════════════════════════════
    PICKLIST VALUES
    ═══════════════════════════════════════════
    Define which picklist values are available for this record type
    -->
    <!--
    <picklistValues>
        <picklist>Status__c</picklist>
        <values>
            <fullName>New</fullName>
            <default>true</default>
        </values>
        <values>
            <fullName>In_Progress</fullName>
            <default>false</default>
        </values>
        <values>
            <fullName>Completed</fullName>
            <default>false</default>
        </values>
    </picklistValues>
    -->
</RecordType>

<!--
    RECORD TYPE USE CASES
    ════════════════════════════════════════════

    1. Account Record Types:
       - Business Account (B2B)
       - Person Account (B2C)
       - Partner Account

    2. Opportunity Record Types:
       - New Business
       - Renewal
       - Upsell/Cross-sell

    3. Case Record Types:
       - Support Case
       - Billing Inquiry
       - Feature Request

    4. Contact Record Types:
       - Customer Contact
       - Partner Contact
       - Internal Contact


    RECORD TYPE BEST PRACTICES
    ════════════════════════════════════════════

    ✓ Use record types when you need:
      - Different page layouts
      - Different picklist values
      - Different sales/support processes
      - Different validation rules (via formula)

    ✓ Keep record type count manageable (3-5 per object max)

    ✓ Assign default record type per profile

    ✓ Consider using formula field for reporting instead of
      multiple record types for simple categorization

    ✗ Don't create record types just for reporting
    ✗ Don't create record types for temporary states
    ✗ Don't create record types that users can't distinguish


    CREATING RECORD TYPE VIA METADATA
    ════════════════════════════════════════════

    File location:
    force-app/main/default/objects/[ObjectName]/recordTypes/[RecordTypeName].recordType-meta.xml

    Example:
    force-app/main/default/objects/Account/recordTypes/Business_Account.recordType-meta.xml

    Also create/update:
    - Page Layout assignments (layoutAssignments in Profile)
    - Picklist value assignments
    - Business Process (for Lead, Opportunity, Case)
-->

<?xml version="1.0" encoding="UTF-8"?>
<!--
    Validation Rule Template

    Usage: Enforce data quality by preventing invalid data entry

    Placeholders:
    - {{RULE_API_NAME}} - API name (e.g., "Require_Close_Date_When_Closed")
    - {{ACTIVE}} - true or false
    - {{DESCRIPTION}} - Rule purpose and business logic
    - {{ERROR_FORMULA}} - Formula that returns TRUE when invalid
    - {{ERROR_FIELD}} - Field to display error on (optional)
    - {{ERROR_MESSAGE}} - User-friendly error message

    Notes:
    - Formula returns TRUE = validation fails (error shown)
    - Formula returns FALSE = validation passes (record saved)
    - Keep formulas simple for maintainability
    - Consider bypass mechanism for integrations/admins
-->
<ValidationRule xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>{{RULE_API_NAME}}</fullName>
    <active>{{ACTIVE}}</active>
    <description>{{DESCRIPTION}}</description>
    <errorConditionFormula>{{ERROR_FORMULA}}</errorConditionFormula>
    <!-- Optional: Display error on specific field instead of top of page -->
    <errorDisplayField>{{ERROR_FIELD}}</errorDisplayField>
    <errorMessage>{{ERROR_MESSAGE}}</errorMessage>
</ValidationRule>

<!--
    COMMON VALIDATION PATTERNS
    ════════════════════════════════════════════

    1. Required Field Based on Status:
    ───────────────────────────────────────────
    AND(
        ISPICKVAL(Status__c, 'Closed'),
        ISBLANK(Close_Date__c)
    )
    Error: "Close Date is required when Status is Closed"

    2. Date Must Be Future:
    ───────────────────────────────────────────
    Due_Date__c < TODAY()
    Error: "Due Date must be in the future"

    3. Date Range Validation:
    ───────────────────────────────────────────
    End_Date__c < Start_Date__c
    Error: "End Date must be after Start Date"

    4. Numeric Range:
    ───────────────────────────────────────────
    OR(
        Discount_Percent__c < 0,
        Discount_Percent__c > 100
    )
    Error: "Discount must be between 0% and 100%"

    5. Email Format:
    ───────────────────────────────────────────
    NOT(REGEX(Email__c, "^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"))
    Error: "Please enter a valid email address"

    6. Phone Format (US):
    ───────────────────────────────────────────
    NOT(REGEX(Phone__c, "^\\(?[0-9]{3}\\)?[-. ]?[0-9]{3}[-. ]?[0-9]{4}$"))
    Error: "Phone must be in format: (XXX) XXX-XXXX"

    7. Cross-Object Validation:
    ───────────────────────────────────────────
    AND(
        NOT(ISBLANK(Account.Type)),
        Account.Type != 'Customer',
        Amount__c > 100000
    )
    Error: "Opportunities over $100K require Customer account type"

    8. Dependent Picklist Enforcement:
    ───────────────────────────────────────────
    AND(
        ISPICKVAL(Type__c, 'Service'),
        NOT(ISPICKVAL(Sub_Type__c, 'Consulting')),
        NOT(ISPICKVAL(Sub_Type__c, 'Support'))
    )
    Error: "Service type requires Consulting or Support sub-type"

    9. Prevent Editing Closed Records:
    ───────────────────────────────────────────
    AND(
        NOT(ISNEW()),
        ISPICKVAL(PRIORVALUE(Status__c), 'Closed'),
        ISCHANGED(Status__c)
    )
    Error: "Cannot reopen closed records"

    10. Bypass Pattern (Recommended):
    ───────────────────────────────────────────
    AND(
        NOT($Permission.Bypass_Validation__c),
        [your validation logic here]
    )
    Note: Create Custom Permission "Bypass_Validation__c" for admins/integrations


    VALIDATION RULE BEST PRACTICES
    ════════════════════════════════════════════

    ✓ Include bypass mechanism for system integrations
    ✓ Use clear, actionable error messages
    ✓ Display error on specific field when possible
    ✓ Document business requirement in description
    ✓ Test with bulk data operations
    ✓ Consider impact on integrations and data loads

    ✗ Don't create complex formulas (hard to maintain)
    ✗ Don't duplicate validation logic in triggers
    ✗ Don't use validation for business logic (use flows/triggers)
    ✗ Don't block system users from fixing data issues
-->

#!/usr/bin/env python3
"""
Permission Set Generator for sf-metadata plugin.

Generates Permission Set XML for custom objects, automatically filtering out:
- Required fields (auto-visible, cannot be in Permission Sets)
- Name fields (always visible)
- Master-Detail fields (controlled by parent)

Usage:
    python3 generate_permission_set.py <object_directory> [--output <path>]

Example:
    python3 generate_permission_set.py force-app/main/default/objects/Customer_Feedback__c

Output:
    force-app/main/default/permissionsets/Customer_Feedback_Access.permissionset-meta.xml
"""

import os
import sys
import argparse
import xml.etree.ElementTree as ET
from pathlib import Path
from typing import List, Dict, Tuple


# XML Namespace for Salesforce metadata
SF_NAMESPACE = "http://soap.sforce.com/2006/04/metadata"
NS = {"sf": SF_NAMESPACE}


def find_element(root, tag_name: str, ns: dict) -> ET.Element:
    """Find element with or without namespace prefix."""
    # Try with namespace first
    elem = root.find(f'.//sf:{tag_name}', ns)
    if elem is not None:
        return elem
    # Try without namespace (default namespace)
    elem = root.find(f'.//{{{SF_NAMESPACE}}}{tag_name}')
    if elem is not None:
        return elem
    # Try plain tag
    elem = root.find(f'.//{tag_name}')
    return elem


def parse_field_metadata(field_path: str) -> Dict:
    """
    Parse a field metadata XML file and extract relevant information.

    Returns dict with:
        - api_name: Field API name
        - required: Whether field is required
        - type: Field type (Text, Number, Picklist, etc.)
        - is_formula: Whether field is a formula
        - is_rollup: Whether field is a roll-up summary
        - is_master_detail: Whether field is a master-detail relationship
    """
    try:
        tree = ET.parse(field_path)
        root = tree.getroot()

        # Handle namespace
        ns = {"sf": SF_NAMESPACE}

        # Extract field name from filename
        filename = os.path.basename(field_path)
        api_name = filename.replace('.field-meta.xml', '')

        # Get field type
        field_type_elem = find_element(root, 'type', ns)
        field_type = field_type_elem.text if field_type_elem is not None else 'Unknown'

        # Check if required
        required_elem = find_element(root, 'required', ns)
        is_required = required_elem is not None and required_elem.text and required_elem.text.lower() == 'true'

        # Check for formula
        formula_elem = find_element(root, 'formula', ns)
        is_formula = formula_elem is not None and formula_elem.text and len(formula_elem.text.strip()) > 0

        # Check for roll-up summary
        is_rollup = field_type == 'Summary'

        # Check for master-detail
        is_master_detail = field_type == 'MasterDetail'

        return {
            'api_name': api_name,
            'required': is_required,
            'type': field_type,
            'is_formula': is_formula,
            'is_rollup': is_rollup,
            'is_master_detail': is_master_detail,
            'path': field_path
        }

    except ET.ParseError as e:
        print(f"  ⚠️ Warning: Could not parse {field_path}: {e}")
        return None
    except Exception as e:
        print(f"  ⚠️ Warning: Error processing {field_path}: {e}")
        return None


def get_object_name(object_dir: str) -> str:
    """Extract object API name from directory path."""
    return os.path.basename(object_dir.rstrip('/'))


def scan_fields(object_dir: str) -> List[Dict]:
    """Scan all field metadata files in an object directory."""
    fields_dir = os.path.join(object_dir, 'fields')
    fields = []

    if not os.path.exists(fields_dir):
        print(f"  ℹ️ No fields directory found at {fields_dir}")
        return fields

    for filename in os.listdir(fields_dir):
        if filename.endswith('.field-meta.xml'):
            field_path = os.path.join(fields_dir, filename)
            field_info = parse_field_metadata(field_path)
            if field_info:
                fields.append(field_info)

    return fields


def filter_fields_for_permission_set(fields: List[Dict], object_name: str) -> Tuple[List[Dict], List[Dict]]:
    """
    Filter fields to determine which should be included in Permission Set.

    Returns:
        (included_fields, excluded_fields)
    """
    included = []
    excluded = []

    for field in fields:
        exclude_reason = None

        # Rule 1: Required fields are auto-visible
        if field['required']:
            exclude_reason = "Required field (auto-visible)"

        # Rule 2: Master-Detail fields controlled by parent
        elif field['is_master_detail']:
            exclude_reason = "Master-Detail (controlled by parent)"

        # Rule 3: Name field is always visible
        elif field['api_name'].lower() == 'name':
            exclude_reason = "Name field (always visible)"

        if exclude_reason:
            field['exclude_reason'] = exclude_reason
            excluded.append(field)
        else:
            included.append(field)

    return included, excluded


def generate_permission_set_xml(object_name: str, included_fields: List[Dict]) -> str:
    """Generate Permission Set XML content."""

    # Create label from object name (remove __c, add spaces)
    label_name = object_name.replace('__c', '').replace('_', ' ')
    perm_set_name = object_name.replace('__c', '') + '_Access'

    xml_content = f'''<?xml version="1.0" encoding="UTF-8"?>
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Auto-generated: Grants full access to {label_name} object and its non-required fields</description>
    <hasActivationRequired>false</hasActivationRequired>
    <label>{label_name} Access</label>

    <!-- Object Permissions: Full CRUD access -->
    <objectPermissions>
        <allowCreate>true</allowCreate>
        <allowDelete>true</allowDelete>
        <allowEdit>true</allowEdit>
        <allowRead>true</allowRead>
        <modifyAllRecords>false</modifyAllRecords>
        <object>{object_name}</object>
        <viewAllRecords>true</viewAllRecords>
    </objectPermissions>
'''

    # Add field permissions
    if included_fields:
        xml_content += '''
    <!-- Field Permissions -->
    <!-- NOTE: Required fields are EXCLUDED (auto-visible in Salesforce) -->
    <!-- NOTE: Formula/Roll-Up fields have editable=false -->
'''
        for field in sorted(included_fields, key=lambda x: x['api_name']):
            # Formula and Roll-Up fields can only be readable
            editable = "false" if (field['is_formula'] or field['is_rollup']) else "true"

            xml_content += f'''    <fieldPermissions>
        <editable>{editable}</editable>
        <field>{object_name}.{field['api_name']}</field>
        <readable>true</readable>
    </fieldPermissions>
'''

    xml_content += '''</PermissionSet>
'''

    return xml_content


def main():
    parser = argparse.ArgumentParser(
        description='Generate Permission Set for a custom object with required field filtering'
    )
    parser.add_argument(
        'object_dir',
        help='Path to object directory (e.g., force-app/main/default/objects/MyObject__c)'
    )
    parser.add_argument(
        '--output', '-o',
        help='Output path for Permission Set file (default: auto-generated in permissionsets/)',
        default=None
    )
    parser.add_argument(
        '--dry-run',
        action='store_true',
        help='Print XML to stdout instead of writing to file'
    )

    args = parser.parse_args()

    object_dir = args.object_dir.rstrip('/')

    # Validate object directory exists
    if not os.path.exists(object_dir):
        print(f"❌ Error: Object directory not found: {object_dir}")
        sys.exit(1)

    object_name = get_object_name(object_dir)
    print(f"\n🔧 Generating Permission Set for: {object_name}")
    print("=" * 60)

    # Scan fields
    print("\n📁 Scanning fields...")
    fields = scan_fields(object_dir)
    print(f"   Found {len(fields)} custom fields")

    # Filter fields
    print("\n🔍 Filtering fields for Permission Set...")
    included, excluded = filter_fields_for_permission_set(fields, object_name)

    # Report excluded fields
    if excluded:
        print(f"\n⚠️ Excluded fields ({len(excluded)}):")
        for field in excluded:
            print(f"   ❌ {field['api_name']}: {field['exclude_reason']}")

    # Report included fields
    if included:
        print(f"\n✅ Included fields ({len(included)}):")
        for field in included:
            field_type = "read-only" if (field['is_formula'] or field['is_rollup']) else "read/write"
            print(f"   ✓ {field['api_name']} ({field_type})")
    else:
        print("\n⚠️ No fields to include in Permission Set")

    # Generate XML
    xml_content = generate_permission_set_xml(object_name, included)

    if args.dry_run:
        print("\n📄 Generated XML (dry-run):")
        print("-" * 60)
        print(xml_content)
        return

    # Determine output path
    if args.output:
        output_path = args.output
    else:
        # Default: create in permissionsets directory at same level as objects
        base_dir = os.path.dirname(os.path.dirname(object_dir))  # Go up from objects/
        perm_sets_dir = os.path.join(base_dir, 'permissionsets')
        perm_set_name = object_name.replace('__c', '') + '_Access'
        output_path = os.path.join(perm_sets_dir, f"{perm_set_name}.permissionset-meta.xml")

    # Create directory if needed
    os.makedirs(os.path.dirname(output_path), exist_ok=True)

    # Write file
    with open(output_path, 'w') as f:
        f.write(xml_content)

    print(f"\n✅ Permission Set generated successfully!")
    print(f"   📁 Location: {output_path}")
    print(f"\n💡 Next steps:")
    print(f"   1. Deploy: sf project deploy start --source-dir {os.path.dirname(output_path)} --target-org <alias>")
    print(f"   2. Assign: sf org assign permset --name {object_name.replace('__c', '')}_Access --target-org <alias>")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Post-Write Validation Hook for sf-metadata plugin.

This hook runs AFTER the Write tool completes and provides validation feedback
for Salesforce metadata files:
- Custom Objects (*.object-meta.xml)
- Custom Fields (*.field-meta.xml)
- Profiles (*.profile-meta.xml)
- Permission Sets (*.permissionset-meta.xml)
- Validation Rules (*.validationRule-meta.xml)
- Record Types (*.recordType-meta.xml)
- Page Layouts (*.layout-meta.xml)

Hook Input (stdin): JSON with tool_input and tool_response
Hook Output (stdout): JSON with optional output message

This hook is ADVISORY - it provides feedback but does not block writes.
"""

import sys
import os
import json

# Add script directory to path for imports
SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
sys.path.insert(0, SCRIPT_DIR)


def validate_metadata(file_path: str) -> dict:
    """
    Run metadata validation on a Salesforce metadata XML file.

    Returns:
        dict with validation results
    """
    try:
        from validate_metadata import MetadataValidator

        validator = MetadataValidator(file_path)
        results = validator.validate()

        # Format output
        score = results.get('overall_score', 0)
        max_score = results.get('max_score', 120)
        rating = results.get('rating', 'Unknown')
        metadata_type = results.get('metadata_type', 'Unknown')
        issues = []

        for category, data in results.get('categories', {}).items():
            for issue in data.get('issues', []):
                issues.append(f"[{issue.get('severity', 'INFO')}] {issue.get('message', '')}")

        output = f"\n🔍 Metadata Validation: {metadata_type}\n"
        output += f"File: {os.path.basename(file_path)}\n"
        output += f"Score: {score}/{max_score} {rating}\n"

        # Show category breakdown
        categories = results.get('categories', {})
        if categories:
            output += "\nCategory Scores:\n"
            for cat_name, cat_data in categories.items():
                cat_score = cat_data.get('score', 0)
                cat_max = cat_data.get('max_score', 20)
                output += f"  ├─ {cat_name}: {cat_score}/{cat_max}\n"

        if issues:
            output += "\nIssues found:\n"
            for issue in issues[:10]:  # Limit to first 10 issues
                output += f"  • {issue}\n"
            if len(issues) > 10:
                output += f"  ... and {len(issues) - 10} more issues\n"
        else:
            output += "✅ No issues found!\n"

        return {
            "continue": True,
            "output": output
        }

    except ImportError as e:
        return {
            "continue": True,
            "output": f"⚠️ Metadata validator not available: {e}"
        }
    except Exception as e:
        return {
            "continue": True,
            "output": f"⚠️ Metadata validation error: {e}"
        }


# Metadata file patterns to validate
METADATA_PATTERNS = [
    ".object-meta.xml",
    ".field-meta.xml",
    ".profile-meta.xml",
    ".permissionset-meta.xml",
    ".validationRule-meta.xml",
    ".recordType-meta.xml",
    ".layout-meta.xml"
]


def is_metadata_file(file_path: str) -> bool:
    """Check if file is a Salesforce metadata file."""
    return any(file_path.endswith(pattern) for pattern in METADATA_PATTERNS)


def main():
    """
    Main hook entry point.

    Reads hook input from stdin, validates metadata files.
    """
    try:
        # Read hook input from stdin
        hook_input = json.load(sys.stdin)

        # Extract file path from tool input
        tool_input = hook_input.get("tool_input", {})
        file_path = tool_input.get("file_path", "")

        # Check if write was successful
        tool_response = hook_input.get("tool_response", {})
        if not tool_response.get("success", True):
            # Write failed, don't validate
            print(json.dumps({"continue": True}))
            return 0

        # Only validate metadata files
        result = {"continue": True}

        if is_metadata_file(file_path):
            result = validate_metadata(file_path)

        # Output result
        print(json.dumps(result))
        return 0

    except json.JSONDecodeError:
        # No valid JSON input, continue silently
        print(json.dumps({"continue": True}))
        return 0
    except Exception as e:
        # Unexpected error, log but don't block
        print(json.dumps({
            "continue": True,
            "output": f"⚠️ Hook error: {e}"
        }))
        return 0


if __name__ == "__main__":
    sys.exit(main())

#!/bin/bash
#
# Run Metadata Validation Script
#
# Usage:
#   ./run_validation.sh <metadata_file>
#
# Example:
#   ./run_validation.sh force-app/main/default/objects/MyObject__c/MyObject__c.object-meta.xml
#
# Validates Salesforce metadata files and provides scoring feedback.
#

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

if [ -z "$1" ]; then
    echo "Usage: $0 <metadata_file>"
    echo ""
    echo "Validates Salesforce metadata files:"
    echo "  - *.object-meta.xml  (Custom Objects)"
    echo "  - *.field-meta.xml   (Custom Fields)"
    echo "  - *.profile-meta.xml (Profiles)"
    echo "  - *.permissionset-meta.xml (Permission Sets)"
    echo ""
    echo "Example:"
    echo "  $0 force-app/main/default/objects/Account/Account.object-meta.xml"
    exit 1
fi

FILE_PATH="$1"

if [ ! -f "$FILE_PATH" ]; then
    echo "Error: File not found: $FILE_PATH"
    exit 1
fi

# Run the Python validator
python3 "$SCRIPT_DIR/validate_metadata.py" "$FILE_PATH"

#!/usr/bin/env python3
"""
Salesforce Metadata Validator

Validates Salesforce metadata XML files against best practices.
120-point scoring across 6 categories:

1. Structure & Format (20 points)
   - Valid XML syntax
   - Correct namespace
   - API version requirements
   - File path structure

2. Naming Conventions (20 points)
   - API names (__c suffix)
   - PascalCase naming
   - Meaningful labels
   - Relationship naming patterns

3. Data Integrity (20 points)
   - Required field defaults
   - Numeric precision/scale
   - Picklist definitions
   - Relationship constraints

4. Security & FLS (20 points)
   - Field-level security considerations
   - Sensitive data patterns
   - Sharing model appropriateness

5. Documentation (20 points)
   - Descriptions present
   - Help text for user fields
   - Error messages for validation rules

6. Best Practices (20 points)
   - Permission Sets over Profiles
   - No hardcoded IDs
   - Global Value Sets for reusable picklists

Usage:
    python validate_metadata.py /path/to/metadata-file.xml
"""

import os
import re
import sys
import xml.etree.ElementTree as ET
from typing import Dict, List, Tuple, Optional


class MetadataValidator:
    """Validates Salesforce metadata XML files."""

    # Salesforce metadata namespace
    NAMESPACE = {'sf': 'http://soap.sforce.com/2006/04/metadata'}

    # Sensitive field patterns (potential PII/security concerns)
    SENSITIVE_PATTERNS = [
        r'ssn|social.?security',
        r'credit.?card|cc.?number',
        r'password|secret|token',
        r'bank.?account|routing.?number',
        r'tax.?id|ein|itin',
        r'driver.?license|passport',
    ]

    # Scoring categories
    CATEGORIES = {
        'structure_format': {'name': 'Structure & Format', 'max': 20, 'score': 20, 'issues': []},
        'naming_conventions': {'name': 'Naming Conventions', 'max': 20, 'score': 20, 'issues': []},
        'data_integrity': {'name': 'Data Integrity', 'max': 20, 'score': 20, 'issues': []},
        'security_fls': {'name': 'Security & FLS', 'max': 20, 'score': 20, 'issues': []},
        'documentation': {'name': 'Documentation', 'max': 20, 'score': 20, 'issues': []},
        'best_practices': {'name': 'Best Practices', 'max': 20, 'score': 20, 'issues': []},
    }

    def __init__(self, file_path: str):
        """Initialize validator with file path."""
        self.file_path = file_path
        self.file_name = os.path.basename(file_path)
        self.tree = None
        self.root = None
        self.metadata_type = self._detect_metadata_type()
        self.categories = {k: dict(v) for k, v in self.CATEGORIES.items()}
        for cat in self.categories.values():
            cat['issues'] = []

    def _detect_metadata_type(self) -> str:
        """Detect metadata type from file name."""
        if self.file_name.endswith('.object-meta.xml'):
            return 'CustomObject'
        elif self.file_name.endswith('.field-meta.xml'):
            return 'CustomField'
        elif self.file_name.endswith('.profile-meta.xml'):
            return 'Profile'
        elif self.file_name.endswith('.permissionset-meta.xml'):
            return 'PermissionSet'
        elif self.file_name.endswith('.validationRule-meta.xml'):
            return 'ValidationRule'
        elif self.file_name.endswith('.recordType-meta.xml'):
            return 'RecordType'
        elif self.file_name.endswith('.layout-meta.xml'):
            return 'Layout'
        return 'Unknown'

    def _add_issue(self, category: str, severity: str, message: str, deduction: int = 0):
        """Add an issue to a category."""
        if category in self.categories:
            self.categories[category]['issues'].append({
                'severity': severity,
                'message': message
            })
            if deduction > 0:
                self.categories[category]['score'] = max(
                    0, self.categories[category]['score'] - deduction
                )

    def _get_text(self, element, tag: str, default: str = '') -> str:
        """Get text content of a child element."""
        child = element.find(f'sf:{tag}', self.NAMESPACE)
        if child is not None and child.text:
            return child.text.strip()
        # Try without namespace
        child = element.find(tag)
        if child is not None and child.text:
            return child.text.strip()
        return default

    def validate(self) -> Dict:
        """Run all validations and return results."""
        # Parse XML
        try:
            self.tree = ET.parse(self.file_path)
            self.root = self.tree.getroot()
        except ET.ParseError as e:
            self._add_issue('structure_format', 'CRITICAL', f'Invalid XML: {e}', 10)
            return self._build_results()
        except FileNotFoundError:
            self._add_issue('structure_format', 'CRITICAL', f'File not found: {self.file_path}', 20)
            return self._build_results()

        # Run validations by metadata type
        self._validate_structure()
        self._validate_naming()
        self._validate_data_integrity()
        self._validate_security()
        self._validate_documentation()
        self._validate_best_practices()

        return self._build_results()

    def _validate_structure(self):
        """Validate XML structure and format."""
        # Check namespace
        root_tag = self.root.tag
        if not root_tag.startswith('{http://soap.sforce.com/2006/04/metadata}'):
            # Check if it has any namespace
            if not root_tag.startswith('{'):
                self._add_issue(
                    'structure_format', 'WARNING',
                    'Missing Salesforce metadata namespace', 5
                )

        # Check file path structure
        if '/objects/' in self.file_path:
            if self.metadata_type == 'CustomField' and '/fields/' not in self.file_path:
                self._add_issue(
                    'structure_format', 'WARNING',
                    'Field files should be in objects/[ObjectName]/fields/', 3
                )
            if self.metadata_type == 'ValidationRule' and '/validationRules/' not in self.file_path:
                self._add_issue(
                    'structure_format', 'WARNING',
                    'Validation rules should be in objects/[ObjectName]/validationRules/', 3
                )

    def _validate_naming(self):
        """Validate naming conventions."""
        # Get API name
        api_name = self._get_text(self.root, 'fullName')
        label = self._get_text(self.root, 'label')

        # Custom objects/fields should end with __c
        if self.metadata_type in ['CustomObject', 'CustomField']:
            # Check filename for __c
            base_name = self.file_name.replace('.object-meta.xml', '').replace('.field-meta.xml', '')
            if not base_name.endswith('__c') and not base_name.startswith('standard-'):
                self._add_issue(
                    'naming_conventions', 'WARNING',
                    f'Custom metadata should have __c suffix: {base_name}', 3
                )

            # Check for PascalCase (allow underscores for API names)
            if api_name and not re.match(r'^[A-Z][a-zA-Z0-9_]*$', api_name.replace('__c', '')):
                self._add_issue(
                    'naming_conventions', 'INFO',
                    f'API name should use PascalCase: {api_name}', 2
                )

        # Check label is meaningful (not just API name)
        if label and api_name:
            api_clean = api_name.replace('__c', '').replace('_', ' ')
            if label.lower() == api_clean.lower():
                self._add_issue(
                    'naming_conventions', 'INFO',
                    'Label should be user-friendly, not just API name', 1
                )

        # Check for abbreviations in labels
        abbreviation_patterns = [
            (r'\bAcct\b', 'Account'),
            (r'\bOpp\b', 'Opportunity'),
            (r'\bCont\b', 'Contact'),
            (r'\bMgr\b', 'Manager'),
            (r'\bNum\b', 'Number'),
            (r'\bQty\b', 'Quantity'),
        ]
        if label:
            for pattern, suggestion in abbreviation_patterns:
                if re.search(pattern, label, re.IGNORECASE):
                    self._add_issue(
                        'naming_conventions', 'INFO',
                        f'Avoid abbreviations in labels. Consider using "{suggestion}"', 1
                    )
                    break

    def _validate_data_integrity(self):
        """Validate data integrity settings."""
        if self.metadata_type == 'CustomField':
            field_type = self._get_text(self.root, 'type')
            required = self._get_text(self.root, 'required')
            default_value = self._get_text(self.root, 'defaultValue')

            # Required fields should have defaults (except lookups)
            if required == 'true' and not default_value:
                if field_type not in ['Lookup', 'MasterDetail']:
                    self._add_issue(
                        'data_integrity', 'INFO',
                        'Required fields should consider having a default value', 2
                    )

            # Number/Currency fields should have precision/scale
            if field_type in ['Number', 'Currency', 'Percent']:
                precision = self._get_text(self.root, 'precision')
                scale = self._get_text(self.root, 'scale')
                if not precision or not scale:
                    self._add_issue(
                        'data_integrity', 'WARNING',
                        f'{field_type} fields should specify precision and scale', 3
                    )

            # Lookup/Master-Detail should have relationship name
            if field_type in ['Lookup', 'MasterDetail']:
                rel_name = self._get_text(self.root, 'relationshipName')
                if not rel_name:
                    self._add_issue(
                        'data_integrity', 'WARNING',
                        'Relationship fields should have relationshipName', 3
                    )

                # Check delete constraint for lookups
                if field_type == 'Lookup':
                    delete_constraint = self._get_text(self.root, 'deleteConstraint')
                    if not delete_constraint:
                        self._add_issue(
                            'data_integrity', 'INFO',
                            'Consider setting deleteConstraint for lookup fields', 2
                        )

        elif self.metadata_type == 'ValidationRule':
            # Check for error message
            error_message = self._get_text(self.root, 'errorMessage')
            if not error_message:
                self._add_issue(
                    'data_integrity', 'WARNING',
                    'Validation rules must have an error message', 5
                )
            elif len(error_message) < 10:
                self._add_issue(
                    'data_integrity', 'INFO',
                    'Error messages should be descriptive', 2
                )

    def _validate_security(self):
        """Validate security and FLS settings."""
        # Check for sensitive field patterns
        api_name = self._get_text(self.root, 'fullName', self.file_name)
        label = self._get_text(self.root, 'label', '')
        description = self._get_text(self.root, 'description', '')

        combined_text = f"{api_name} {label} {description}".lower()

        for pattern in self.SENSITIVE_PATTERNS:
            if re.search(pattern, combined_text, re.IGNORECASE):
                self._add_issue(
                    'security_fls', 'CRITICAL',
                    f'Potential sensitive data field detected. Ensure proper FLS and encryption.', 10
                )
                break

        # Check sharing model for objects
        if self.metadata_type == 'CustomObject':
            sharing_model = self._get_text(self.root, 'sharingModel')
            if sharing_model == 'ReadWrite':
                self._add_issue(
                    'security_fls', 'INFO',
                    'Public Read/Write sharing model - verify this is intentional', 2
                )

        # For Permission Sets/Profiles, check for ModifyAllData or ViewAllData
        if self.metadata_type in ['Profile', 'PermissionSet']:
            user_perms = self.root.findall('.//sf:userPermissions', self.NAMESPACE)
            for perm in user_perms:
                name = self._get_text(perm, 'name')
                enabled = self._get_text(perm, 'enabled')
                if enabled == 'true' and name in ['ModifyAllData', 'ViewAllData']:
                    self._add_issue(
                        'security_fls', 'WARNING',
                        f'{name} permission enabled - use with caution', 5
                    )

    def _validate_documentation(self):
        """Validate documentation elements."""
        description = self._get_text(self.root, 'description')
        help_text = self._get_text(self.root, 'inlineHelpText')

        # Check for description
        if self.metadata_type in ['CustomObject', 'CustomField', 'PermissionSet']:
            if not description:
                self._add_issue(
                    'documentation', 'WARNING',
                    'Add a description to explain the purpose', 5
                )
            elif len(description) < 20:
                self._add_issue(
                    'documentation', 'INFO',
                    'Description should be more detailed', 2
                )

        # Check for help text on user-facing fields
        if self.metadata_type == 'CustomField':
            field_type = self._get_text(self.root, 'type')
            # User-facing fields should have help text
            if field_type not in ['Formula', 'Summary'] and not help_text:
                self._add_issue(
                    'documentation', 'INFO',
                    'Consider adding help text for user guidance', 2
                )

        # Validation rules should have good error messages
        if self.metadata_type == 'ValidationRule':
            error_message = self._get_text(self.root, 'errorMessage')
            if error_message and not any(word in error_message.lower() for word in ['please', 'must', 'should', 'required']):
                self._add_issue(
                    'documentation', 'INFO',
                    'Error messages should be user-friendly and actionable', 2
                )

    def _validate_best_practices(self):
        """Validate against Salesforce best practices."""
        if self.metadata_type == 'Profile':
            self._add_issue(
                'best_practices', 'INFO',
                'Consider using Permission Sets instead of Profiles for granular access', 3
            )

        if self.metadata_type == 'CustomField':
            field_type = self._get_text(self.root, 'type')

            # Check for formula fields with hardcoded IDs
            if field_type == 'Formula':
                formula = self._get_text(self.root, 'formula')
                if formula and re.search(r'["\'][0-9a-zA-Z]{15,18}["\']', formula):
                    self._add_issue(
                        'best_practices', 'WARNING',
                        'Avoid hardcoded IDs in formulas - use Custom Settings or Custom Metadata', 5
                    )

            # Picklist fields should consider Global Value Sets
            if field_type == 'Picklist':
                value_set = self.root.find('.//sf:valueSetDefinition', self.NAMESPACE)
                if value_set is not None:
                    values = value_set.findall('.//sf:value', self.NAMESPACE)
                    if len(values) > 10:
                        self._add_issue(
                            'best_practices', 'INFO',
                            'Consider using a Global Value Set for reusable picklist values', 2
                        )

        if self.metadata_type == 'ValidationRule':
            # Check for bypass pattern
            formula = self._get_text(self.root, 'errorConditionFormula')
            if formula and '$Permission' not in formula and '$Setup' not in formula:
                self._add_issue(
                    'best_practices', 'INFO',
                    'Consider adding a bypass mechanism for admin/integration users', 3
                )

    def _build_results(self) -> Dict:
        """Build and return validation results."""
        total_score = sum(cat['score'] for cat in self.categories.values())
        max_score = sum(cat['max'] for cat in self.categories.values())

        # Calculate rating
        percentage = (total_score / max_score) * 100 if max_score > 0 else 0
        if percentage >= 90:
            rating = '⭐⭐⭐⭐⭐ Excellent'
        elif percentage >= 80:
            rating = '⭐⭐⭐⭐ Very Good'
        elif percentage >= 70:
            rating = '⭐⭐⭐ Good'
        elif percentage >= 60:
            rating = '⭐⭐ Needs Work'
        else:
            rating = '⭐ Critical Issues'

        return {
            'file_path': self.file_path,
            'metadata_type': self.metadata_type,
            'overall_score': total_score,
            'max_score': max_score,
            'rating': rating,
            'categories': {
                cat_key: {
                    'name': cat_data['name'],
                    'score': cat_data['score'],
                    'max_score': cat_data['max'],
                    'issues': cat_data['issues']
                }
                for cat_key, cat_data in self.categories.items()
            }
        }


def main():
    """CLI entry point with dual-mode input support."""
    import json

    file_path = None

    # Mode 1: Hook mode - read from stdin JSON (PostToolUse hooks)
    if not sys.stdin.isatty():
        try:
            hook_input = json.load(sys.stdin)
            tool_input = hook_input.get("tool_input", {})
            file_path = tool_input.get("file_path", "")
        except (json.JSONDecodeError, EOFError):
            pass

    # Mode 2: CLI mode - read from command-line argument
    if not file_path and len(sys.argv) >= 2:
        file_path = sys.argv[1]

    # Validate we have a file path
    if not file_path:
        print("Usage: python validate_metadata.py <metadata-file.xml>")
        sys.exit(1)

    # Only validate metadata files
    valid_extensions = [
        '.object-meta.xml', '.field-meta.xml', '.permissionset-meta.xml',
        '.profile-meta.xml', '.validationRule-meta.xml', '.recordType-meta.xml',
        '.layout-meta.xml'
    ]
    if not any(file_path.endswith(ext) for ext in valid_extensions):
        sys.exit(0)  # Silently skip non-metadata files

    validator = MetadataValidator(file_path)
    results = validator.validate()

    # Print results
    print(f"\n{'=' * 60}")
    print(f"🔍 Metadata Validation: {results['metadata_type']}")
    print(f"File: {os.path.basename(file_path)}")
    print(f"{'=' * 60}")
    print(f"\nScore: {results['overall_score']}/{results['max_score']} {results['rating']}")

    print("\nCategory Breakdown:")
    for cat_key, cat_data in results['categories'].items():
        score = cat_data['score']
        max_score = cat_data['max_score']
        name = cat_data['name']
        pct = int((score / max_score) * 100) if max_score > 0 else 0
        print(f"  ├─ {name}: {score}/{max_score} ({pct}%)")

    # Print issues
    all_issues = []
    for cat_data in results['categories'].values():
        all_issues.extend(cat_data['issues'])

    if all_issues:
        print("\nIssues Found:")
        for issue in all_issues:
            severity = issue['severity']
            message = issue['message']
            icon = {'CRITICAL': '🔴', 'WARNING': '🟡', 'INFO': '🔵'}.get(severity, '⚪')
            print(f"  {icon} [{severity}] {message}")
    else:
        print("\n✅ No issues found!")

    print()
    return 0 if results['overall_score'] >= 72 else 1


if __name__ == "__main__":
    sys.exit(main())