sfcc-dev-mcp 1.0.16 → 1.0.20

package/ai-instructions/skills/sfcc-forms-development/references/ARCHITECTURE-SGJC-SFRA.md

@@ -1,143 +0,0 @@
-# Advanced SFCC Forms Architecture (SiteGenesis vs SFRA)
-
-This reference is for architects and senior devs designing or migrating form flows (login, registration, checkout, account, complex configuration).
-
-## 1) Architectural Foundations
-
-The SFCC Forms Framework is not “just HTML forms.” It is a stateful, server-side framework that:
-- instantiates a form object from XML definitions
-- maintains state across requests (session-scoped)
-- enforces server-side type/constrain validation
-- supports complex multi-step flows
-
-### XML Form Definition = Server-Side Contract
-
-Form XML defines:
-- structure (fields/groups/lists)
-- parsing rules + constraints
-- resource keys (labels + errors)
-- action-level validation behavior
-
-Treat it like a schema contract between templates and controllers.
-
-## 2) Form Object Lifecycle
-
-- Form instances are stored in session scope.
-- State persists unless cleared.
-- Locale changes can invalidate/clear session form values.
-
-Operational rules:
-- Clear before rendering a “fresh” form.
-- Clear after successful submission to prevent resubmission and leakage.
-
-## 3) Validation Strategy (Defense in Depth)
-
-### Client-side validation
-
-- Purpose: UX and immediate feedback.
-- Security: none (can be bypassed).
-
-### Server-side validation
-
-- Authoritative gate.
-- Runs against XML constraints automatically.
-
-Per-field precedence (typical):
-1. parsing/type/regexp
-2. mandatory
-3. range/length bounds
-4. custom invalidation
-
-## 4) Security Architecture
-
-### CSRF
-
-Use the platform’s synchronizer token pattern correctly:
-- Generate token on form render.
-- Require token on any state-changing POST.
-
-SFRA:
-- Use CSRF middleware (`generateToken` on GET; `validateRequest` / `validateAjaxRequest` on POST).
-
-SiteGenesis:
-- Use `dw.web.CSRFProtection` explicitly (validate early, before processing).
-
-### XSS
-
-Forms are major injection vectors.
-
-Rule:
-- Always output-encode user-provided values in ISML.
-
-When rendering user data, prefer explicit encoding contexts (e.g., HTML content).
-
-### DoS / Payload abuse
-
-- Always set `max-length` on string fields.
-- Avoid expensive regex patterns.
-- Keep server-side validation and error generation efficient.
-
-## 5) Persistence and Transaction Management
-
-All writes to persistent objects must occur inside a transaction:
-- Use `dw.system.Transaction.wrap`.
-
-Guidelines:
-- Keep transactions short.
-- Do not do network calls inside transactions.
-- Map values explicitly when persisting (avoid mass assignment).
-
-### SFRA: route:BeforeComplete pattern
-
-A robust pattern is:
-- validate + decide outside the transaction
-- register persistence in `route:BeforeComplete`
-- write data inside `Transaction.wrap`
-
-This keeps the request pipeline clean and reduces accidental double-writes.
-
-## 6) SiteGenesis (SGJC) vs SFRA: Key Differences
-
-| Concern | SiteGenesis (SGJC) | SFRA |
-|---|---|---|
-| Controller model | guard-driven actions (classic) | middleware chains (`server.get/post`) |
-| Form access | `pdict.CurrentForms` / `app.getForm` | `server.forms.getForm()` |
-| Template coupling | templates can touch live session form | templates should consume serialized form data |
-| CSRF | often manual validation | middleware-driven |
-| Persistence | mixed into controller callbacks | often isolated via `route:BeforeComplete` |
-| Binding style | can be implicit/mass assignment | explicit assignment encouraged |
-
-### SiteGenesis specifics
-
-- Input names are generated and can vary (commonly `dwfrm_...`).
-- Templates must use generated names (e.g., `field.htmlName`) rather than hardcoding.
-
-## 7) Migration Checklist (SiteGenesis ➜ SFRA)
-
-1. Copy XML form definitions into the SFRA cartridge.
-2. Ensure labels/errors live in resource bundles (`templates/resources/*.properties`).
-3. Replace guard controller logic with SFRA routes.
-4. Enforce:
-   - HTTPS
-   - POST-only for state changes
-   - CSRF middleware validation
-5. Replace implicit binding with explicit mapping inside `Transaction.wrap`.
-6. Update templates to:
-   - use SFRA view model
-   - inject CSRF using `pdict.csrf.*`
-   - output-encode displayed values
-7. Clear form state at appropriate times.
-
-## 8) Secure Forms Checklist
-
-```text
-[ ] POST + HTTPS enforced
-[ ] CSRF validate before touching form data
-[ ] Server-side validation gates all writes
-[ ] Transactions are short and isolated
-[ ] Explicit mapping for writes
-[ ] max-length on strings
-[ ] Regex patterns are conservative
-[ ] Output encoding for any user data
-[ ] Clear session form state (pre-render and/or post-success)
-```

package/ai-instructions/skills/sfcc-forms-development/references/FORM-XML-CHEATSHEET.md

@@ -1,127 +0,0 @@
-# SFCC Form XML Cheat Sheet
-
-This is a practical reference for the storefront Forms Framework XML definitions found under `cartridge/forms/**`.
-
-## What the XML Controls
-
-- Form structure (fields, groups, lists)
-- Data types and parsing
-- Built-in constraint validation
-- Resource keys for labels/descriptions/errors
-- Actions (which submissions trigger full validation)
-
-## Minimum Recommended Constraints
-
-| Field Type | Must Have | Why |
-|---|---|---|
-| `string` | `max-length` | Prevent overly large payloads; reduce DoS/storage risk |
-| `string` + regexp | conservative `regexp` | Avoid ReDoS and ambiguous formats |
-| `integer` / `number` | `min`/`max` (when applicable) | Prevent negative/invalid ranges |
-| any mandatory | `missing-error` | Clear, localized feedback |
-
-## Core Elements
-
-### `<form>`
-
-```xml
-<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
-    <!-- fields / groups / lists / actions -->
-</form>
-```
-
-### `<field>`
-
-Common attributes (subset):
-
-- `formid` (required): identifier
-- `type` (required): `string`, `integer`, `number`, `boolean`, `date`
-- `label`: resource key
-- `mandatory`: `true|false`
-- `max-length` / `min-length` (strings)
-- `min` / `max` (numbers)
-- `regexp` (strings)
-- `format` (dates)
-- error keys: `missing-error`, `parse-error`, `range-error`, `value-error`
-
-Example:
-
-```xml
-<field formid="postalCode" type="string"
-       label="form.address.postal"
-       mandatory="true"
-       max-length="20"
-       regexp="^[A-Za-z0-9\-\s]{3,20}$"
-       missing-error="form.address.postal.required"
-       parse-error="form.address.postal.invalid"/>
-```
-
-### Error Key Semantics (Server-Side)
-
-When a form is submitted, constraint checks are evaluated in a predictable “first failing rule wins” manner for each field:
-
-1. Parse/type/regexp problems → `parse-error`
-2. Mandatory empty → `missing-error`
-3. Range / min/max / length bounds → `range-error`
-4. Script-triggered invalidation → `value-error` (or custom key)
-
-### `<group>`
-
-Use groups to namespace complex objects like addresses.
-
-```xml
-<group formid="shippingAddress">
-    <field formid="firstName" type="string" mandatory="true" max-length="50"/>
-    <field formid="lastName" type="string" mandatory="true" max-length="50"/>
-</group>
-```
-
-Controller access pattern:
-
-```text
-form.shippingAddress.firstName.value
-```
-
-### `<list>`
-
-Use lists for repeated groups (saved addresses, payment instruments, etc.).
-
-Guideline:
-- Treat list items as independent sub-forms with their own validity.
-- Avoid deeply nested lists; keep templates and controller logic readable.
-
-### `<action>`
-
-Actions decide whether “valid form” constraints run.
-
-```xml
-<action formid="submit" valid-form="true"/>
-<action formid="cancel" valid-form="false"/>
-```
-
-## Reuse via `<include>`
-
-Use includes to avoid repeating canonical definitions (address, phone, etc.).
-
-Pattern:
-- Create an address form definition once.
-- Include it into checkout/profile forms.
-
-This keeps validation consistent and reduces drift.
-
-## Locale-Specific Definitions
-
-If the structure truly differs by locale (not just labels), define locale-specific XML:
-
-```
-/forms/default/profile.xml
-/forms/pt_BR/profile.xml
-```
-
-The platform loads the best match for the current request locale.
-
-## Anti-Patterns
-
-- No `max-length` on string fields.
-- Aggressive, complex regex patterns (risk of catastrophic backtracking).
-- Hardcoding labels/errors instead of resource keys.
-- Depending on implicit binding/mass assignment to persist sensitive fields.

package/ai-instructions/skills/sfcc-fraud-prevention/SKILL.md

@@ -1,95 +0,0 @@
----
-name: sfcc-fraud-prevention
-description: Layered fraud prevention playbook for Salesforce B2C Commerce developers. Use this when adding fraud signals, designing a risk scoring approach, integrating third-party tools, or hardening checkout/login against bot-driven abuse.
----
-
-# SFCC Fraud Prevention (Developer Playbook)
-
-Fraud prevention in SFCC is a *system*, not a single feature. This skill focuses on practical developer responsibilities:
-- Detectable signals you can implement
-- Where to enforce checks
-- How to store state safely
-- How to avoid performance and quota pitfalls
-
-## Quick Checklist
-
-```text
-[ ] Start at the edge: eCDN rules (block obvious bad traffic)
-[ ] Enforce payment checks (AVS/CVV/3DS where available)
-[ ] Add server-side validation (never trust the client)
-[ ] Add velocity + behavior checks using minimal state
-[ ] Ensure retention + purge jobs for any temporary state objects
-[ ] Log decisions carefully (no PII leakage)
-```
-
-## Threat Taxonomy (Why It Matters to Code)
-
-Common families you’ll see in data:
-- Card-not-present fraud
-- Account takeover (credential stuffing)
-- “Friendly fraud” / chargebacks
-- Bot-driven attacks (card testing, inventory hoarding)
-
-Your job is to translate these into **signals** you can observe and validate.
-
-## Actionable Signals (Implementation-Friendly)
-
-| Signal type | Examples |
-|---|---|
-| Data mismatches | IP geolocation vs billing/shipping country; name/address anomalies |
-| Velocity patterns | many attempts from same IP/email/device; repeated failures then success |
-| Order characteristics | unusually large order; high-risk SKUs; rush shipping |
-| Identity indicators | disposable email; gibberish names; repeated address reuse |
-
-## Layered Defense Architecture
-
-### 1) Edge controls (before app servers)
-- Use **eCDN custom rules** to block/limit known abusive traffic patterns.
-- Rate-limit endpoints that are common bot targets (login, add-to-cart, checkout).
-
-### 2) Platform + processor basics
-- Enable/enforce payment gateway features like **AVS** and **CVV** checks.
-- Prefer adding friction only when risk is elevated.
-
-### 3) Server-side rules and scoring
-Where to implement depends on architecture:
-- **SFRA**: controller middleware + fraud detection script points
-- **Headless**: keep hook logic minimal; consider custom endpoints for heavier checks
-
-A practical approach:
-- Compute a numeric risk score from signals (0–100)
-- Block above a threshold; challenge (CAPTCHA/step-up) in mid-range; allow below threshold
-
-## State Storage (Don’t Create a Quota Time Bomb)
-
-If you store historical signals:
-- Use a minimal schema (counts + timestamps), not raw event logs
-- Define retention policy and a purge job from day one
-
-If you must store per-session state:
-- Prefer session privacy storage for small values
-
-## Logging & Observability
-
-- Log risk decisions with correlation IDs and *redacted* values
-- Avoid writing PII into shared logs
-
-See also: `sfcc-logging` and `sfcc-security`.
-
-## When to Buy Instead of Build
-
-Third-party fraud tools can be the correct choice when:
-- You need global intelligence across merchants
-- You need chargeback guarantees
-- You are being hit by sophisticated bot abuse
-
-Build custom logic when:
-- You need business-specific heuristics
-- You have clear signals + small scope
-- You can commit to continuous tuning (false positives are costly)
-
-## References
-- Rhino Inquisitor: A Developer’s Guide to Combating Fraud on SFCC
-  - https://www.rhino-inquisitor.com/a-dev-guide-to-combating-fraud-on-sfcc/
-- Salesforce: Bot management guidance (high-level responsibility model)
-  - https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html

package/ai-instructions/skills/sfcc-hooks-registration/SKILL.md

@@ -1,39 +0,0 @@
----
-name: sfcc-hooks-registration
-description: 'Register SFCC hooks via cartridge package.json and hooks.json. Use when adding hooks or troubleshooting hook registration.'
----
-
-# SFCC Hooks Registration
-
-## When to Use
-- Adding new script hooks for a cartridge
-- Fixing missing hook execution
-- Verifying hook registration structure
-
-## Procedure
-1. Add a package.json at the top level of the cartridge (cartridges/<cartridge-name>/package.json).
-2. Define the hooks path relative to that package.json:
-   ```json
-   {
-     "hooks": "./cartridge/scripts/hooks.json"
-   }
-   ```
-3. In hooks.json, map hook names to script files relative to hooks.json:
-   ```json
-   {
-     "hooks": [
-       {
-         "name": "dw.order.calculate",
-         "script": "./hooks/cart/calculate.js"
-       }
-     ]
-   }
-   ```
-4. Export hook functions as CommonJS exports with the unqualified hook name (for example, `dw.order.calculate` uses `exports.calculate`).
-5. Enable the **Salesforce Commerce Cloud API hook execution** feature switch in Business Manager for OCAPI/SCAPI hooks.
-6. Ensure the cartridge is in the site cartridge path and upload the cartridge.
-
-## Notes
-- The hooks path is relative to the package.json location.
-- The script path in hooks.json is relative to hooks.json itself.
-- For Shopper API hooks, returning a value can skip the system implementation; return nothing when you want the default implementation to run.