@salesforce/afv-skills 1.7.4 → 1.8.0

package/skills/developing-datacloud-code-extension/references/quick-reference.md

@@ -0,0 +1,269 @@
+# Data Cloud Code Extension - Quick Reference
+
+## Command Cheat Sheet
+
+### Initialize Project
+```bash
+# Create script project
+sf data-code-extension script init --package-dir <directory>
+
+# Create function project
+sf data-code-extension function init --package-dir <directory>
+
+# Examples
+sf data-code-extension script init --package-dir .
+sf data-code-extension script init --package-dir my-transform
+```
+
+### Scan for Permissions
+```bash
+# Basic scan
+sf data-code-extension script scan --entrypoint ./payload/entrypoint.py
+
+# Preview without saving
+sf data-code-extension script scan --entrypoint ./payload/entrypoint.py --dry-run
+
+# Custom config location
+sf data-code-extension script scan --entrypoint ./payload/entrypoint.py --config ./custom-config.json
+
+# Skip requirements.txt
+sf data-code-extension script scan --entrypoint ./payload/entrypoint.py --no-requirements
+```
+
+### Run Locally
+```bash
+# Basic run
+sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org <org_alias>
+
+# With custom config
+sf data-code-extension script run --entrypoint ./payload/entrypoint.py -o <org_alias> -c custom-config.json
+
+# Examples
+sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org afvibe
+sf data-code-extension script run --entrypoint ./payload/entrypoint.py -o afvibe
+```
+
+### Deploy
+```bash
+# Minimal deployment (MUST include --package-dir ./payload)
+sf data-code-extension script deploy \
+  --target-org <org_alias> \
+  --name <name> \
+  --package-version <version> \
+  --description "<description>" \
+  --package-dir ./payload
+
+# Full options
+sf data-code-extension script deploy \
+  --target-org <org_alias> \
+  --name <name> \
+  --package-version <version> \
+  --description "<description>" \
+  --cpu-size <CPU_L|CPU_XL|CPU_2XL|CPU_4XL> \
+  --package-dir ./payload
+
+# Examples (CRITICAL: Always include --package-dir ./payload)
+sf data-code-extension script deploy \
+  --target-org afvibe \
+  --name Employee_Upper \
+  --package-version 1.0.0 \
+  --description "Uppercase employee positions" \
+  --package-dir ./payload
+```
+
+## Common Workflows
+
+### New Project from Scratch
+```bash
+# 1. Create directory
+mkdir my-transform && cd my-transform
+
+# 2. Initialize
+sf data-code-extension script init --package-dir .
+
+# 3. Edit payload/entrypoint.py with your transformation
+
+# 4. Scan
+sf data-code-extension script scan --entrypoint ./payload/entrypoint.py
+
+# 5. Test
+sf data-code-extension script run --entrypoint ./payload/entrypoint.py --target-org afvibe
+
+# 6. Deploy (MUST include --package-dir ./payload)
+sf data-code-extension script deploy \
+  --target-org afvibe \
+  --name MyTransform \
+  --package-version 1.0.0 \
+  --description "My transformation" \
+  --package-dir ./payload
+```
+
+### Update Existing Code Extension
+```bash
+# 1. Edit payload/entrypoint.py
+
+# 2. Re-scan
+sf data-code-extension script scan --entrypoint ./payload/entrypoint.py
+
+# 3. Test
+sf data-code-extension script run --entrypoint ./payload/entrypoint.py -o afvibe
+
+# 4. Deploy with new version (include --package-dir ./payload)
+sf data-code-extension script deploy \
+  -o afvibe \
+  -n MyTransform \
+  --package-version 1.1.0 \
+  --description "Updated transformation" \
+  --package-dir ./payload
+```
+
+## Python Code Patterns
+
+### Read/Write DLO
+```python
+from datacustomcode import Client
+
+client = Client()
+
+# Read
+df = client.read_dlo('Employee__dll')
+
+# Transform
+df['new_field'] = df['old_field'].str.upper()
+
+# Write (modes: 'overwrite', 'append')
+client.write_to_dlo('Output__dll', df, 'overwrite')
+```
+
+### Read/Write DMO
+```python
+# Read
+df = client.read_dmo('EmployeeDMO')
+
+# Write (modes: 'upsert', 'insert')
+client.write_to_dmo('EmployeeDMO', df, 'upsert')
+```
+
+### Multiple DLO Operations
+```python
+# Read multiple
+employees = client.read_dlo('Employee__dll')
+departments = client.read_dlo('Department__dll')
+
+# Join
+merged = employees.merge(departments, on='dept_id')
+
+# Write multiple
+client.write_to_dlo('Enriched__dll', merged, 'overwrite')
+client.write_to_dmo('EmployeeDMO', merged, 'upsert')
+```
+
+### Data Transformations
+```python
+import pandas as pd
+
+# Filter
+active = df[df['status'] == 'Active']
+
+# Computed column
+df['full_name'] = df['first'] + ' ' + df['last']
+
+# Aggregate
+summary = df.groupby('dept')['salary'].mean()
+
+# Conditional
+df['grade'] = df['position'].apply(
+    lambda x: 'Senior' if 'VP' in x else 'Junior'
+)
+```
+
+## Option Reference
+
+### --cpu-size
+- `CPU_L` - Small datasets (< 1M records)
+- `CPU_XL` - Medium datasets (1M-5M)
+- `CPU_2XL` - Large datasets (5M-10M) **[default]**
+- `CPU_4XL` - Very large (> 10M records)
+
+### Write Modes
+- `overwrite` - Replace all data
+- `append` - Add to existing data
+- `upsert` - Update or insert (DMO only)
+- `insert` - Insert only (DMO only)
+
+## Troubleshooting Quick Fixes
+
+```bash
+# Plugin not found
+sf plugins install @salesforce/plugin-data-codeextension
+
+# Python SDK missing
+pip install salesforce-data-customcode
+
+# Verify Python version (must be 3.11.x)
+python --version
+
+# Org not connected
+sf org login web --alias <org_alias>
+
+# Config missing
+sf data-code-extension script scan --entrypoint ./payload/entrypoint.py
+
+# Docker not running (for deploy)
+# Start Docker Desktop
+```
+
+## File Structure
+
+```
+my-project/
+├── payload/
+│   ├── entrypoint.py      # Main code
+│   └── config.json        # Auto-generated permissions
+├── requirements.txt       # Auto-generated dependencies
+└── README.md
+```
+
+## config.json Format
+
+```json
+{
+  "version": "1.0",
+  "permissions": {
+    "read": ["Employee__dll", "Department__dll"],
+    "write": ["Enriched__dll"]
+  },
+  "resources": {
+    "cpu_size": "CPU_2XL"
+  }
+}
+```
+
+## Common Errors
+
+| Error | Quick Fix |
+|-------|-----------|
+| Plugin not found | `sf plugins install @salesforce/plugin-data-codeextension` |
+| Python SDK missing | `pip install salesforce-data-customcode` |
+| Wrong Python version | Use pyenv to install 3.11.0 |
+| Org not connected | `sf org login web --alias <alias>` |
+| Config missing | Run scan command |
+| DLO not found | Check DLO name, use getting-datacloud-schema skill |
+| Docker error | Start Docker Desktop |
+
+## Deployment Checklist
+
+- [ ] Code written in entrypoint.py
+- [ ] Scanned for permissions
+- [ ] Tested locally
+- [ ] Version number decided
+- [ ] Description added
+- [ ] CPU size chosen
+- [ ] Docker running
+- [ ] Org authenticated
+
+## Resources
+
+- Plugin: https://github.com/salesforcecli/plugin-data-code-extension
+- Python SDK: https://github.com/forcedotcom/datacloud-customcode-python-sdk
+- Data Cloud Docs: https://help.salesforce.com/s/articleView?id=sf.c360_a_intro.htm

package/skills/generating-apex/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-apex
-description: Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex.
+description: "Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex."
+metadata:
+  version: "1.0"
 ---
 
 # Generating Apex
@@ -403,4 +405,4 @@ Deploy: <dry-run or next step>
 
 ## Troubleshooting Boundary
 
-This skill handles production `.cls`/`.trigger`/`.apex` issues only: compile/parse failures, deployment dependency errors, runtime governor-limit failures. For test execution, assertions, coverage, or `sf apex run test` failures, delegate to `generating-apex-test`.
+This skill handles production `.cls`/`.trigger`/`.apex` issues only: compile/parse failures, deployment dependency errors, runtime governor-limit failures. For test execution, assertions, coverage, or `sf apex run test` failures, delegate to `generating-apex-test`.

package/skills/generating-apex-test/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-apex-test
-description: Generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking strategies, assertion best practices, and disciplined test-fix loops. Use this skill when creating new Apex test classes, improving test coverage, debugging and fixing failing Apex tests, running test execution and coverage analysis, or implementing testing patterns for triggers, services, controllers, batch jobs, queueables, and integrations. Triggers on *Test.cls, *_Test.cls files, sf apex run test workflows, coverage reports, test-fix loops. Do NOT trigger for production Apex code (use generating-apex) or Jest/LWC tests.
+description: "Generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking strategies, assertion best practices, and disciplined test-fix loops. Use this skill when creating new Apex test classes, improving test coverage, debugging and fixing failing Apex tests, running test execution and coverage analysis, or implementing testing patterns for triggers, services, controllers, batch jobs, queueables, and integrations. Triggers on *Test.cls, *_Test.cls files, sf apex run test workflows, coverage reports, test-fix loops. Do NOT trigger for production Apex code (use generating-apex) or Jest/LWC tests."
+metadata:
+  version: "1.0"
 ---
 
 # Generating Apex Tests

package/skills/generating-custom-application/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-custom-application
 description: "Use this skill when users need to create or configure Salesforce Custom Applications. Trigger when users mention custom apps, application metadata, app navigation, or organizing tabs into applications. Use when users want to create app containers for tabs and pages. Always use this skill for custom application work."
+metadata:
+  version: "1.0"
 ---
 
 ## When to Use This Skill

package/skills/generating-custom-field/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-custom-field
 description: "Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, or field metadata. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, or formula issues. Always use this skill for any custom field metadata work, field generation, or field troubleshooting."
+metadata:
+  version: "1.0"
 ---
 
 ## When to Use This Skill
@@ -498,4 +500,4 @@ Before generating CustomField XML, verify:
 
 ### Naming Checks
 - [ ] Is the API name free of reserved words (`Order`, `Group`, `Select`, etc.)?
-- [ ] Is the API name unique on this object?
+- [ ] Is the API name unique on this object?

package/skills/generating-custom-lightning-type/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-custom-lightning-type
 description: "Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. This is complex - always use this skill for CLT work."
+metadata:
+  version: "1.0"
 ---
 
 ## When to Use This Skill

package/skills/generating-custom-object/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-custom-object
 description: "Use this skill when users need to create, generate, or validate Salesforce Custom Object metadata. Trigger when users mention custom objects, creating objects, object metadata, .object files, sharing models, name fields, or validation rules on objects. Also use when users say things like \"create a custom object\", \"generate object metadata\", \"set up an object for...\", or when they're troubleshooting object deployment errors especially around sharing models and Master-Detail relationships. Always use this skill for any custom object metadata work."
+metadata:
+  version: "1.0"
 ---
 
 ## When to Use This Skill
@@ -235,4 +237,4 @@ Before generating the Custom Object XML, verify:
 ### Architectural Checks
 - [ ] Is `<description>` present with a meaningful summary?
 - [ ] Are `<enableSearch>` and `<enableReports>` set to `true` if user-facing?
-- [ ] Does the filename match the intended API name?
+- [ ] Does the filename match the intended API name?

package/skills/generating-custom-tab/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-custom-tab
 description: "Use this skill when users need to create or configure Salesforce Custom Tabs. Trigger when users mention tabs, navigation tabs, object tabs, web tabs, Visualforce tabs, Lightning component tabs, app page tabs, or tab configuration. Also use when users want to add navigation to custom objects, create tabs for external content, or set up Lightning page tabs. Always use this skill for any custom tab work."
+metadata:
+  version: "1.0"
 ---
 
 ## When to Use This Skill
@@ -151,4 +153,4 @@ Also forbidden:
 - Follow consistent naming conventions
 - Object tab files MUST only contain `<customObject>true</customObject>` and `<motif>` — nothing else
 - Web tab files MUST only contain: `<customObject>false</customObject>`, `<label>`, `<motif>`, `<url>`, `<urlEncodingKey>`, and optionally `<description>`, `<frameHeight>` — nothing else
-- Never include `<isHidden>`, `<tabVisibility>`, `<type>`, `<mobileReady>`, or empty elements
+- Never include `<isHidden>`, `<tabVisibility>`, `<type>`, `<mobileReady>`, or empty elements

package/skills/generating-flexipage/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-flexipage
 description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like 'create a Lightning page', 'add a component to a page', 'customize the record page', 'generate a FlexiPage', or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention 'page' in the context of Salesforce."
+metadata:
+  version: "1.0"
 ---
 
 ## When to Use This Skill

package/skills/generating-flow/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-flow
 description: "Generate Salesforce Flows using the MCP tool execute_metadata_action. Use when the user asks to create, build, or generate a flow — including Screen, Autolaunched, Record-Triggered (before/after-save), Scheduled. Also trigger for flow-like requests such as \"when a record is created\", \"trigger daily at\", \"send an email when\", \"update the field when\", \"automate\", \"workflow\", or \"flow XML/metadata\". This is the only skill for Salesforce Flow generation."
+metadata:
+  version: "1.0"
 ---
 
 ## Goal

package/skills/generating-lightning-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-lightning-app
-description: Build complete Salesforce Lightning Experience applications from natural language descriptions. Use this skill when a user requests a "complete app", "Lightning app", "business solution", "management system", or describes a scenario requiring multiple interconnected Salesforce components (objects, fields, pages, tabs, security). Orchestrates all required metadata types in proper dependency order to produce a deployable application.
+description: "Build complete Salesforce Lightning Experience applications from natural language descriptions. Use this skill when a user requests a \"complete app\", \"Lightning app\", \"business solution\", \"management system\", or describes a scenario requiring multiple interconnected Salesforce components (objects, fields, pages, tabs, security). Orchestrates all required metadata types in proper dependency order to produce a deployable application."
 metadata:
   version: "1.0"
   related-skills: generating-custom-object, generating-custom-field, generating-custom-tab, generating-flexipage, generating-custom-application, generating-flow, generating-validation-rule, generating-list-view, generating-permission-set

package/skills/generating-list-view/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-list-view
 description: "Use this skill when users need to create, generate, or validate Salesforce List View metadata. Trigger when users mention list views, filtered record lists, creating views, setting up record columns, filtering records by criteria, or ask about list view visibility. Also use when users say things like \"I need a view that shows...\", \"filter records by...\", \"create a list view for...\", or when they're working with ListView XML files and need validation or troubleshooting."
+metadata:
+  version: "1.0"
 ---
 
 ## When to Use This Skill

package/skills/generating-permission-set/SKILL.md

@@ -3,7 +3,7 @@ name: generating-permission-set
 description: "Generates correct, deployable Salesforce permission set metadata (PermissionSet XML) with object, field, user, and app permissions. Use this skill when creating or editing permission set metadata, object permissions, field-level security (FLS), tab visibility, or deploying permission sets."
 compatibility: Salesforce Metadata API v60.0+
 metadata:
-  author: afv-library
+  author: sf-skills
   version: "1.0"
 ---
 

package/skills/generating-ui-bundle-features/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-ui-bundle-features
 description: "MUST activate when the project contains a uiBundles/*/src/ directory and the user wants to add authentication or search to their app. Use this skill when adding authentication or search to a UI bundle app. Only covers two features: authentication (login, logout, protected routes, session management) and search (global search across pages and content). Always use this skill for these two features instead of building from scratch."
+metadata:
+  version: "1.0"
 ---
 
 # UI Bundle Features

package/skills/generating-ui-bundle-metadata/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-ui-bundle-metadata
 description: "MUST activate when the project contains a uiBundles/*/src/ directory and scaffolding a new UI bundle or app, or when editing ui-bundle.json, .uibundle-meta.xml, or CSP trusted site files. Use this skill when scaffolding with sf template generate ui-bundle, configuring ui-bundle.json (routing, headers, outputDir), or registering CSP Trusted Sites. Activate when the task involves files matching *.uibundle-meta.xml, ui-bundle.json, or cspTrustedSites/*.cspTrustedSite-meta.xml."
+metadata:
+  version: "1.0"
 ---
 
 # UI Bundle Metadata

package/skills/generating-ui-bundle-site/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-ui-bundle-site
 description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves creating or configuring site infrastructure. Use this skill when creating or configuring a Salesforce Digital Experience Site for hosting a UI bundle. Activate when files matching digitalExperiences/, networks/, customSite/, or DigitalExperienceBundle exist and need modification, or when the user wants to publish, host, or configure guest access for their app."
+metadata:
+  version: "1.0"
 ---
 
 # Digital Experience Site for React UI Bundles

package/skills/generating-validation-rule/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: generating-validation-rule
 description: "Use this skill when users need to create, modify, or validate Salesforce Validation Rules. Trigger when users mention validation rules, field validation, data quality rules, formula validation, error messages, or validation logic. Also use when users encounter validation errors, need to update formulas, or want to enforce business rules at the data layer. Always use this skill for any validation rule work."
+metadata:
+  version: "1.0"
 ---
 
 ## When to Use This Skill