@decocms/start 0.19.0

package/.cursor/skills/deco-site-patterns/section-patterns.md

@@ -0,0 +1,340 @@
+# Section Patterns
+
+Sections are the primary building blocks of a Deco storefront. They are Preact components registered in the manifest and configurable via the CMS admin.
+
+## Section File Conventions
+
+### Pattern 1: Re-export
+
+The section file re-exports a component from `components/`. Keeps the section thin and the component reusable.
+
+```typescript
+// sections/HeaderRetrofit/Header.tsx
+export { default } from "$store/components/headerRetrofit/Header.tsx";
+
+export const LoadingFallback = () => <div class="absolute" />;
+```
+
+### Pattern 2: Wrapper with Loader
+
+The section wraps a component and adds a loader for server-side data:
+
+```typescript
+// sections/HeroBannerRetrofit/HeroBanner.tsx
+import HeroBanner from "$store/components/uiRetrofit/HeroBanner/HeroBanner.tsx";
+import { MatchDevice } from "apps/website/matchers/device.ts";
+
+export interface Props {
+  /** @title Banner desktop */
+  desktop: BannerProps;
+  /** @title Banner mobile */
+  mobile: BannerProps;
+}
+
+export default function HeroBannerWrapper(props: Props & { isMobile: boolean }) {
+  return <HeroBanner {...props} />;
+}
+
+export function loader(props: Props, req: Request, ctx: AppContext) {
+  return { ...props, isMobile: MatchDevice(req.headers, "mobile") };
+}
+```
+
+### Pattern 3: Full Implementation
+
+The section contains both component and loader logic in one file (or re-exports both from a component file):
+
+```typescript
+// sections/ProductRetrofit/ProductDetails.tsx
+export { default, loader } from "../../components/productRetrofit/Details/index.tsx";
+```
+
+Where the component file has:
+
+```typescript
+// components/productRetrofit/Details/index.tsx
+export interface Props {
+  page: ProductDetailsPage | null;
+  /** @title Enable 3D View */
+  enableThreeDView?: boolean;
+}
+
+export default function ProductDetails({ page, enableThreeDView }: Props) {
+  if (!page) return <NotFound />;
+  return <div>...</div>;
+}
+
+export const loader = async (props: Props, req: Request, ctx: AppContext) => {
+  const { credentials } = await ctx.get({ "__resolveType": "Tokens" });
+  const isMobile = MatchDevice(req.headers, "mobile");
+  // Fetch additional data, check user, etc.
+  return { ...props, isMobile, credentials };
+};
+```
+
+## JSDoc Annotations for Admin
+
+JSDoc tags on props control how the admin renders form fields.
+
+### @title -- Field Label
+
+```typescript
+interface Props {
+  /** @title Titulo principal */
+  heading: string;
+}
+```
+
+### @description -- Help Text
+
+```typescript
+interface Props {
+  /**
+   * @title Cor de fundo
+   * @description Define a cor de fundo da pagina
+   */
+  backgroundColor?: string;
+}
+```
+
+### @format -- Input Type
+
+| Format | Admin Input | Example |
+|--------|-------------|---------|
+| `color` | Color picker | `@format color` on `string` |
+| `html` | Rich text editor | `@format html` on `string` |
+| `textarea` | Multiline text | `@format textarea` on `string` |
+
+```typescript
+interface Props {
+  /**
+   * @title Cor primaria
+   * @format color
+   * @default #003232
+   */
+  primary: string;
+
+  /** @format html */
+  richContent: string;
+
+  /** @format textarea */
+  description: string;
+}
+```
+
+### @default -- Default Value
+
+```typescript
+interface Props {
+  /**
+   * @title Cor base
+   * @format color
+   * @default #FFFFFF
+   */
+  "base-100": string;
+}
+```
+
+### @ignore -- Hide from Admin
+
+```typescript
+interface Props {
+  /** @ignore */
+  isMobile?: boolean;
+}
+```
+
+Used for loader-injected props that shouldn't appear in the admin form.
+
+## Widget Types
+
+Import from `apps/admin/widgets.ts` to get special admin input types:
+
+```typescript
+import { ImageWidget } from "apps/admin/widgets.ts";
+import { HTMLWidget } from "apps/admin/widgets.ts";
+import { VideoWidget } from "apps/admin/widgets.ts";
+import { Secret } from "apps/website/loaders/secret.ts";
+```
+
+| Type | Admin Input | Usage |
+|------|-------------|-------|
+| `ImageWidget` | Image uploader (Deco CDN) | Banners, logos, product images |
+| `HTMLWidget` | Rich text editor | Descriptions, content blocks |
+| `VideoWidget` | Video URL input | Video sections |
+| `Secret` | Encrypted value (not shown) | API keys, tokens |
+
+Legacy alias: `ImageWidget as LiveImage` is common in older sites.
+
+```typescript
+interface Props {
+  /** @description Mobile optimized image */
+  srcMobile: ImageWidget;
+  /** @description Desktop optimized image */
+  srcDesktop?: ImageWidget;
+  alt: string;
+  href: string;
+}
+```
+
+## Loader Patterns
+
+### Sync Loader (MatchDevice)
+
+The most common pattern. Adds `isMobile` for responsive rendering:
+
+```typescript
+import { MatchDevice } from "apps/website/matchers/device.ts";
+import { AppContext } from "site/apps/site.ts";
+
+export function loader(props: Props, req: Request, _ctx: AppContext) {
+  return {
+    ...props,
+    isMobile: MatchDevice(req.headers, "mobile"),
+  };
+}
+```
+
+Used in ~18 sections (HeroBanner, PromoBar, ContentSection, CollectionBlock, etc.).
+
+### Async Loader (Data Fetching)
+
+For sections that need server-side data:
+
+```typescript
+export const loader = async (props: Props, req: Request, ctx: AppContext) => {
+  // Resolve secrets via __resolveType
+  const { credentials } = await ctx.get({ "__resolveType": "Tokens" });
+
+  // Call VTEX API
+  const response = await fetch(`https://${account}.vtexcommercestable.com.br/api/...`, {
+    headers: { "X-VTEX-API-AppKey": credentials.appKey },
+  });
+
+  // Check user status
+  const user = await ctx.invoke("site/actions/checkUser.ts");
+
+  return { ...props, data: await response.json(), user, isMobile: MatchDevice(req.headers, "mobile") };
+};
+```
+
+Used in ProductDetails, SearchResult, OurStores, InstagramPosts.
+
+### CMS-Wired Data (No Loader Needed)
+
+When data comes from the CMS via `__resolveType`, the section receives it as a resolved prop -- no loader needed:
+
+```typescript
+interface Props {
+  products: Product[] | null;  // Admin shows loader selector
+  title: string;               // Admin shows text input
+}
+
+export default function ProductShelf({ products, title }: Props) {
+  if (!products) return null;
+  return <div>{title}{products.map(p => <Card product={p} />)}</div>;
+}
+```
+
+The admin lets the editor choose which loader provides `products` (e.g., `vtex/loaders/intelligentSearch/productListingPage.ts`).
+
+## LoadingFallback Pattern
+
+Sections can export a `LoadingFallback` component that renders while the section's loader is pending (async rendering):
+
+### Simple Placeholder
+
+```typescript
+export const LoadingFallback = () => <div class="absolute" />;
+```
+
+Prevents layout shift with a minimal placeholder.
+
+### Spinner
+
+```typescript
+export function LoadingFallback() {
+  return (
+    <div style={{ height: "600px" }} class="flex justify-center items-center">
+      <span class="loading loading-spinner" />
+    </div>
+  );
+}
+```
+
+Fixed-height container with a loading spinner.
+
+### Skeleton with Props
+
+Uses `Partial<Props>` to render a structural skeleton that matches the final layout:
+
+```typescript
+export function LoadingFallback(props: Partial<Props>) {
+  return (
+    <div class="container">
+      {props.title && <h2>{props.title}</h2>}
+      {props.breadcrumb && <Breadcrumb items={props.breadcrumb} />}
+      <div class="flex justify-center items-center h-[400px]">
+        <span class="loading loading-spinner" />
+      </div>
+    </div>
+  );
+}
+```
+
+The CMS static props (title, breadcrumb) render immediately while loader data is pending.
+
+### Animated Skeleton
+
+Full skeleton with pulse animation placeholders:
+
+```typescript
+function CollectionContentSkeleton() {
+  return (
+    <div class="grid grid-cols-2 lg:grid-cols-4 gap-4">
+      {Array.from({ length: 8 }).map((_, i) => (
+        <div key={i} class="animate-pulse">
+          <div class="bg-gray-200 aspect-square rounded" />
+          <div class="bg-gray-200 h-4 mt-2 rounded w-3/4" />
+          <div class="bg-gray-200 h-4 mt-1 rounded w-1/2" />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export function LoadingFallback(props: Partial<Props>) {
+  return (
+    <div class="container">
+      <CollectionContentSkeleton />
+    </div>
+  );
+}
+```
+
+## Section Organization
+
+### Naming Convention
+
+- `{Domain}Retrofit/` prefix groups related sections (e.g., `ProductRetrofit/`, `HeaderRetrofit/`)
+- "Retrofit" indicates a redesigned version; new sites may drop this suffix
+- One file per section, named after the component
+
+### Grouping
+
+| Group | Sections |
+|-------|----------|
+| Product | ProductDetails, ProductShelf, SearchResult, WishlistRetrofit |
+| Navigation | Header, Footer, PromoBar |
+| Content | HeroBanner, Banner, Carousel, ImageGallery, Video, Text |
+| Institutional | FAQ, About, ContactUs, OurStores |
+| Marketing | Newsletter, PopupFirstTime, CampaignTimer |
+| Infrastructure | Theme, Seo, Analytics, CookieConsent |
+
+### Section vs Component vs Island
+
+| Layer | Location | Renders | Purpose |
+|-------|----------|---------|---------|
+| Section | `sections/` | Server (SSR) | CMS block, registered in manifest |
+| Component | `components/` | Server (SSR) | Reusable, not in manifest |
+| Island | `islands/` | Client (hydrated) | Interactive, has client-side JS |

package/.cursor/skills/deco-site-scaling-tuning/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: deco-site-scaling-tuning
+description: Discover optimal autoscaling parameters for a Deco site by analyzing Prometheus metrics. Correlates CPU, concurrency, and latency to find the right scaling target and method.
+---
+
+# Deco Site Scaling Tuning
+
+Analyze a site's Prometheus metrics to discover the optimal autoscaling parameters. This skill helps you find the CPU/concurrency threshold where latency degrades and recommends scaling configuration accordingly.
+
+## When to Use This Skill
+
+- A site is overscaled (too many pods for its traffic)
+- A site oscillates between scaling up and down (panic mode loop)
+- Need to switch scaling metric (concurrency vs CPU vs RPS)
+- Need to find the right target value for a site
+- After deploying scaling changes, to verify they're working
+
+## Prerequisites
+
+- `kubectl` access to the target cluster
+- Prometheus accessible via port-forward (from `kube-prometheus-stack` in monitoring namespace)
+- Python 3 for analysis scripts
+- At least 6 hours of metric history for meaningful analysis
+- **For direct latency data**: queue-proxy PodMonitor must be applied (see Step 0)
+
+## Quick Start
+
+```
+0. ENABLE METRICS   → Apply queue-proxy PodMonitor if not already done
+1. PORT-FORWARD     → kubectl port-forward prometheus-pod 19090:9090
+2. COLLECT DATA     → Run analysis scripts against Prometheus
+3. ANALYZE          → Find CPU threshold where latency degrades
+4. RECOMMEND        → Choose scaling metric and target
+5. APPLY            → Use deco-site-deployment skill to apply changes
+6. VERIFY           → Monitor for 1-2 hours after change
+```
+
+## Files in This Skill
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Overview, methodology, analysis procedures |
+| `analysis-scripts.md` | Ready-to-use Python scripts for Prometheus queries |
+
+## Step 0: Enable Queue-Proxy Metrics (one-time)
+
+Queue-proxy runs as a sidecar on every Knative pod and exposes request latency histograms. These are critical for precise tuning but are **not scraped by default**.
+
+Apply this PodMonitor:
+
+```yaml
+apiVersion: monitoring.coreos.com/v1
+kind: PodMonitor
+metadata:
+  name: knative-queue-proxy
+  namespace: monitoring
+  labels:
+    release: kube-prometheus-stack
+spec:
+  namespaceSelector:
+    any: true
+  selector:
+    matchExpressions:
+      - key: serving.knative.dev/revision
+        operator: Exists
+  podMetricsEndpoints:
+    - port: http-usermetric
+      path: /metrics
+      interval: 15s
+```
+
+```bash
+kubectl apply -f queue-proxy-podmonitor.yaml
+# Wait 2-3 hours for data to accumulate before running latency analysis
+```
+
+**Metrics unlocked by this PodMonitor:**
+- `revision_app_request_latencies_bucket` — request latency histogram (p50/p95/p99)
+- `revision_app_request_latencies_sum` / `_count` — for avg latency
+- `revision_app_request_count` — request rate by response code
+
+## Step 1: Establish Prometheus Connection
+
+```bash
+PROM_POD=$(kubectl get pods -n monitoring -l app.kubernetes.io/name=prometheus -o jsonpath='{.items[0].metadata.name}')
+kubectl port-forward -n monitoring $PROM_POD 19090:9090 &
+# Verify
+curl -s "http://127.0.0.1:19090/api/v1/query?query=up" | jq '.status'
+```
+
+## Step 2: Collect Current State
+
+Before analyzing, understand what the site is currently configured for.
+
+### 2a. Read current autoscaler config
+
+```bash
+SITENAME="<sitename>"
+NS="sites-${SITENAME}"
+
+# Current revision annotations
+kubectl get rev -n $NS -o json | \
+  jq '.items[] | select(.status.conditions[]?.status == "True" and .status.conditions[]?.type == "Active") |
+  {name: .metadata.name, annotations: .metadata.annotations | with_entries(select(.key | startswith("autoscaling")))}'
+
+# Global autoscaler defaults
+kubectl get cm config-autoscaler -n knative-serving -o json | jq '.data | del(._example)'
+```
+
+### 2b. Current pod count and resources
+
+```bash
+kubectl get pods -n $NS --no-headers | wc -l
+kubectl top pods -n $NS --no-headers | head -20
+```
+
+## Step 3: Run Analysis
+
+Use the scripts in `analysis-scripts.md`. The analysis follows this methodology:
+
+### Methodology: Finding the Optimal CPU Target
+
+**Goal:** Find the CPU level at which latency starts to degrade. This is your scaling target — keep pods below this CPU to maintain good latency.
+
+**Approach:**
+
+1. **Collect CPU per pod, concurrency per pod, pod count, and (if available) request latency** over 6-12 hours
+2. **Bucket data by CPU range** (0-200m, 200-300m, ..., 700m+)
+3. **For each bucket**, compute avg/p95 concurrency per pod
+4. **Compute the "latency inflation factor"** — how much concurrency increases beyond what the pod count reduction explains:
+   ```
+   excess = (avg_conc_above_threshold / avg_conc_below_threshold) / (avg_pods_below / avg_pods_above)
+   ```
+   - excess = 1.0 → concurrency increase fully explained by fewer pods (no latency degradation)
+   - excess > 1.0 → latency is inflating concurrency (pods are slowing down)
+   - The CPU level where excess crosses ~1.5x is your inflection point
+
+5. **If queue-proxy latency is available**, directly plot avg latency vs CPU — the hockey stick inflection is your target
+
+### What to Look For
+
+```
+CPU vs Concurrency/pod:
+
+  Low CPU   (0-200m)   →  Low conc/pod   →  Pods are idle (overprovisioned)
+  Medium CPU (200-400m) →  Moderate conc  →  Healthy range
+  ★ INFLECTION ★       →  Conc jumps      →  Latency starting to degrade
+  High CPU  (500m+)    →  High conc/pod   →  Pods overloaded, latency bad
+```
+
+The inflection point is where you want your scaling target.
+
+### Decision Matrix
+
+**IMPORTANT:** CPU target is in **millicores** (not percentage). E.g., `target: 400` means scale when CPU reaches 400m.
+
+| Inflection CPU | Recommended metric | Target | Notes |
+|---------------|-------------------|--------|-------|
+| < CPU request | CPU scaling | target = inflection value in millicores | Standard case |
+| ~ CPU request | CPU scaling | target = CPU_request × 0.8 | Conservative |
+| > CPU request (no limit) | CPU scaling | target = CPU_request × 0.8, increase CPU request | Need more CPU headroom |
+| No clear inflection | Concurrency scaling | Keep current but tune target | CPU isn't the bottleneck |
+
+### Common Patterns
+
+**Pattern: CPU-bound app (Deno SSR)**
+- Baseline CPU: 200-300m (Deno runtime + V8 JIT)
+- Inflection: 400-500m
+- Recommendation: CPU scaling with target = inflection (e.g., 400 millicores)
+
+**Pattern: IO-bound app (mostly external API calls)**
+- CPU stays low even under high concurrency
+- Inflection not visible in CPU
+- Recommendation: Keep concurrency scaling, tune the target
+
+**Pattern: Oscillating (panic loop)**
+- Symptoms: pods cycle between min and max
+- Cause: concurrency scaling + low target + `scale-down-delay` ratchet
+- Fix: Switch to CPU scaling (breaks the latency→concurrency feedback loop)
+
+## Step 4: Apply Changes
+
+Use the `deco-site-deployment` skill to:
+1. Update the `state` secret with new scaling config
+2. Redeploy on both clouds
+
+Example for CPU-based scaling (target is in millicores):
+```bash
+NEW_STATE=$(echo "$STATE" | jq '
+  .scaling.metric = {
+    "type": "cpu",
+    "target": 400
+  }
+')
+```
+
+## Step 5: Verify After Change
+
+Monitor for 1-2 hours after applying changes:
+
+```bash
+# Watch pod count stabilize
+watch -n 10 "kubectl get pods -n sites-<sitename> --no-headers | wc -l"
+
+# Check if panic mode triggers (should be N/A for HPA/CPU)
+# HPA doesn't have panic mode — this is one of the advantages
+
+# Verify HPA is active
+kubectl get hpa -n sites-<sitename>
+
+# Check HPA status
+kubectl describe hpa -n sites-<sitename>
+```
+
+### Success Criteria
+
+- Pod count stabilizes (no more oscillation)
+- Avg CPU per pod stays below your target during normal traffic
+- CPU crosses target only during genuine traffic spikes (and scales up proportionally)
+- No panic mode events (HPA doesn't have panic mode)
+- Latency stays acceptable (check with queue-proxy metrics if available)
+
+### Rollback
+
+If the new scaling is worse, revert by changing the state secret back to concurrency scaling:
+```bash
+NEW_STATE=$(echo "$STATE" | jq '
+  .scaling.metric = {
+    "type": "concurrency",
+    "target": 15,
+    "targetUtilizationPercentage": 70
+  }
+')
+```
+
+## Related Skills
+
+- `deco-site-deployment` — Apply scaling changes and redeploy
+- `deco-site-memory-debugging` — Debug memory issues on running pods
+- `deco-incident-debugging` — Incident response and triage