@rune-kit/rune 2.8.0 → 2.11.0

package/extensions/ecommerce/skills/shopify-dev.md

@@ -1,69 +1,69 @@
----
-name: "shopify-dev"
-pack: "@rune/ecommerce"
-description: "Shopify development patterns — Liquid templates, Shopify API, Hydrogen/Remix storefronts, metafields, theme architecture, webhook HMAC verification."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# shopify-dev
-
-Shopify development patterns — Liquid templates, Shopify API, Hydrogen/Remix storefronts, metafields, theme architecture, webhook HMAC verification.
-
-#### Workflow
-
-**Step 1 — Detect Shopify architecture**
-Use Glob to find `shopify.app.toml`, `*.liquid`, `remix.config.*`, `hydrogen.config.*`. Use Grep to find Storefront API queries (`#graphql`), Admin API calls, metafield references, and API version strings. Classify: theme app extension, custom app, or Hydrogen storefront.
-
-**Step 2 — Audit theme and API usage**
-Check for:
-- Liquid templates without `| escape` filter on user-generated metafield content (XSS vulnerability)
-- Storefront API queries without pagination (`first: 250` max — cursor-based pagination required for larger sets)
-- Hardcoded product IDs or variant IDs (break when products are recreated)
-- Missing metafield type validation (metafield can be deleted/recreated with different type)
-- Theme sections without `schema` blocks (limits merchant customization)
-- Deprecated API version usage (Shopify deprecates versions on a rolling 12-month cycle)
-- Webhook handlers without HMAC signature verification (anyone can POST fake events)
-
-**Step 3 — Emit optimized patterns**
-For Hydrogen: emit typed Storefront API loader with proper caching and pagination. For theme: emit section schema with metafield integration. For apps: emit webhook handler with HMAC verification and idempotency.
-
-#### Example
-
-```typescript
-// Hydrogen — typed Storefront API loader with caching + pagination
-import { json, type LoaderFunctionArgs } from '@shopify/remix-oxygen';
-
-const PRODUCTS_QUERY = `#graphql
-  query Products($first: Int!, $after: String) {
-    products(first: $first, after: $after) {
-      pageInfo { hasNextPage endCursor }
-      nodes {
-        id handle title
-        variants(first: 10) {
-          nodes { id title price { amount currencyCode } availableForSale }
-        }
-        metafield(namespace: "custom", key: "care_instructions") { value type }
-      }
-    }
-  }
-` as const;
-
-export async function loader({ context }: LoaderFunctionArgs) {
-  const { products } = await context.storefront.query(PRODUCTS_QUERY, {
-    variables: { first: 24 },
-    cache: context.storefront.CacheLong(),
-  });
-  return json({ products });
-}
-
-// Webhook handler with HMAC verification (Express)
-import crypto from 'crypto';
-
-function verifyShopifyWebhook(req: Request, secret: string): boolean {
-  const hmac = req.headers['x-shopify-hmac-sha256'] as string;
-  const body = (req as any).rawBody; // Must capture raw body before JSON parse
-  const hash = crypto.createHmac('sha256', secret).update(body, 'utf8').digest('base64');
-  return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(hmac));
-}
-```
+---
+name: "shopify-dev"
+pack: "@rune/ecommerce"
+description: "Shopify development patterns — Liquid templates, Shopify API, Hydrogen/Remix storefronts, metafields, theme architecture, webhook HMAC verification."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# shopify-dev
+
+Shopify development patterns — Liquid templates, Shopify API, Hydrogen/Remix storefronts, metafields, theme architecture, webhook HMAC verification.
+
+#### Workflow
+
+**Step 1 — Detect Shopify architecture**
+Use Glob to find `shopify.app.toml`, `*.liquid`, `remix.config.*`, `hydrogen.config.*`. Use Grep to find Storefront API queries (`#graphql`), Admin API calls, metafield references, and API version strings. Classify: theme app extension, custom app, or Hydrogen storefront.
+
+**Step 2 — Audit theme and API usage**
+Check for:
+- Liquid templates without `| escape` filter on user-generated metafield content (XSS vulnerability)
+- Storefront API queries without pagination (`first: 250` max — cursor-based pagination required for larger sets)
+- Hardcoded product IDs or variant IDs (break when products are recreated)
+- Missing metafield type validation (metafield can be deleted/recreated with different type)
+- Theme sections without `schema` blocks (limits merchant customization)
+- Deprecated API version usage (Shopify deprecates versions on a rolling 12-month cycle)
+- Webhook handlers without HMAC signature verification (anyone can POST fake events)
+
+**Step 3 — Emit optimized patterns**
+For Hydrogen: emit typed Storefront API loader with proper caching and pagination. For theme: emit section schema with metafield integration. For apps: emit webhook handler with HMAC verification and idempotency.
+
+#### Example
+
+```typescript
+// Hydrogen — typed Storefront API loader with caching + pagination
+import { json, type LoaderFunctionArgs } from '@shopify/remix-oxygen';
+
+const PRODUCTS_QUERY = `#graphql
+  query Products($first: Int!, $after: String) {
+    products(first: $first, after: $after) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        id handle title
+        variants(first: 10) {
+          nodes { id title price { amount currencyCode } availableForSale }
+        }
+        metafield(namespace: "custom", key: "care_instructions") { value type }
+      }
+    }
+  }
+` as const;
+
+export async function loader({ context }: LoaderFunctionArgs) {
+  const { products } = await context.storefront.query(PRODUCTS_QUERY, {
+    variables: { first: 24 },
+    cache: context.storefront.CacheLong(),
+  });
+  return json({ products });
+}
+
+// Webhook handler with HMAC verification (Express)
+import crypto from 'crypto';
+
+function verifyShopifyWebhook(req: Request, secret: string): boolean {
+  const hmac = req.headers['x-shopify-hmac-sha256'] as string;
+  const body = (req as any).rawBody; // Must capture raw body before JSON parse
+  const hash = crypto.createHmac('sha256', secret).update(body, 'utf8').digest('base64');
+  return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(hmac));
+}
+```

package/extensions/ecommerce/skills/subscription-billing.md

@@ -1,93 +1,93 @@
----
-name: "subscription-billing"
-pack: "@rune/ecommerce"
-description: "Subscription billing — trial management, proration, dunning (failed payment retry), plan changes mid-cycle, usage-based billing, cancellation flows."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# subscription-billing
-
-Subscription billing — trial management, proration, dunning (failed payment retry), plan changes mid-cycle, usage-based billing, cancellation flows.
-
-#### Workflow
-
-**Step 1 — Detect subscription setup**
-Use Grep to find: `stripe.subscriptions`, `subscription`, `recurring`, `billing_cycle`, `trial`, `prorate`, `dunning`. Check for Stripe Billing Portal, customer portal redirect, and subscription lifecycle webhook handlers.
-
-**Step 2 — Audit subscription lifecycle**
-Check for:
-- Trial-to-paid transition: is payment method collected during trial signup? (If not, 60%+ of trials churn at conversion — Stripe data)
-- Proration on plan change: `proration_behavior` defaults to `create_prorations` — mid-cycle upgrade charges immediately. Must explicitly choose behavior and communicate to user
-- Failed payment handling: Stripe retries automatically per Smart Retries settings, but app must handle `invoice.payment_failed` webhook to notify user, restrict access, or trigger custom retry
-- Cancellation: `cancel_at_period_end` vs immediate cancel — immediate loses remaining period revenue. Most SaaS should use `cancel_at_period_end` and show countdown
-- Missing webhook handlers for: `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed`, `invoice.paid`
-- Usage-based billing: meter events must be sent before invoice finalization (not after) — late events are lost
-
-**Step 3 — Emit subscription patterns**
-Emit: subscription creation with trial + payment method upfront, plan change with explicit proration, dunning webhook handler, and cancellation flow.
-
-#### Example
-
-```typescript
-// Create subscription with trial — collect payment method upfront
-async function createSubscription(customerId: string, priceId: string, trialDays: number) {
-  // Verify customer has payment method BEFORE creating subscription
-  const paymentMethods = await stripe.paymentMethods.list({
-    customer: customerId, type: 'card',
-  });
-  if (paymentMethods.data.length === 0) {
-    throw new Error('Payment method required before starting trial');
-  }
-
-  return stripe.subscriptions.create({
-    customer: customerId,
-    items: [{ price: priceId }],
-    trial_period_days: trialDays,
-    payment_settings: {
-      payment_method_types: ['card'],
-      save_default_payment_method: 'on_subscription',
-    },
-    trial_settings: {
-      end_behavior: { missing_payment_method: 'cancel' }, // Auto-cancel if no card at trial end
-    },
-    expand: ['latest_invoice.payment_intent'],
-  });
-}
-
-// Plan change with explicit proration
-async function changePlan(subscriptionId: string, newPriceId: string) {
-  const subscription = await stripe.subscriptions.retrieve(subscriptionId);
-  return stripe.subscriptions.update(subscriptionId, {
-    items: [{ id: subscription.items.data[0].id, price: newPriceId }],
-    proration_behavior: 'always_invoice', // Charge/credit immediately
-    payment_behavior: 'error_if_incomplete', // Fail if upgrade payment fails
-  });
-}
-
-// Dunning webhook — restrict access after payment failure
-app.post('/webhooks/subscription', async (req, res) => {
-  const event = verifyStripeEvent(req);
-
-  switch (event.type) {
-    case 'invoice.payment_failed': {
-      const invoice = event.data.object as Stripe.Invoice;
-      const attempt = invoice.attempt_count;
-      if (attempt >= 3) {
-        // After 3 failed retries, restrict access (don't cancel yet)
-        await userService.setStatus(invoice.customer as string, 'past_due');
-        await emailService.send(invoice.customer_email!, 'payment-failed-final');
-      } else {
-        await emailService.send(invoice.customer_email!, 'payment-failed-retry', { attempt });
-      }
-      break;
-    }
-    case 'customer.subscription.deleted': {
-      const sub = event.data.object as Stripe.Subscription;
-      await userService.deactivate(sub.customer as string);
-      break;
-    }
-  }
-  res.json({ received: true });
-});
-```
+---
+name: "subscription-billing"
+pack: "@rune/ecommerce"
+description: "Subscription billing — trial management, proration, dunning (failed payment retry), plan changes mid-cycle, usage-based billing, cancellation flows."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# subscription-billing
+
+Subscription billing — trial management, proration, dunning (failed payment retry), plan changes mid-cycle, usage-based billing, cancellation flows.
+
+#### Workflow
+
+**Step 1 — Detect subscription setup**
+Use Grep to find: `stripe.subscriptions`, `subscription`, `recurring`, `billing_cycle`, `trial`, `prorate`, `dunning`. Check for Stripe Billing Portal, customer portal redirect, and subscription lifecycle webhook handlers.
+
+**Step 2 — Audit subscription lifecycle**
+Check for:
+- Trial-to-paid transition: is payment method collected during trial signup? (If not, 60%+ of trials churn at conversion — Stripe data)
+- Proration on plan change: `proration_behavior` defaults to `create_prorations` — mid-cycle upgrade charges immediately. Must explicitly choose behavior and communicate to user
+- Failed payment handling: Stripe retries automatically per Smart Retries settings, but app must handle `invoice.payment_failed` webhook to notify user, restrict access, or trigger custom retry
+- Cancellation: `cancel_at_period_end` vs immediate cancel — immediate loses remaining period revenue. Most SaaS should use `cancel_at_period_end` and show countdown
+- Missing webhook handlers for: `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed`, `invoice.paid`
+- Usage-based billing: meter events must be sent before invoice finalization (not after) — late events are lost
+
+**Step 3 — Emit subscription patterns**
+Emit: subscription creation with trial + payment method upfront, plan change with explicit proration, dunning webhook handler, and cancellation flow.
+
+#### Example
+
+```typescript
+// Create subscription with trial — collect payment method upfront
+async function createSubscription(customerId: string, priceId: string, trialDays: number) {
+  // Verify customer has payment method BEFORE creating subscription
+  const paymentMethods = await stripe.paymentMethods.list({
+    customer: customerId, type: 'card',
+  });
+  if (paymentMethods.data.length === 0) {
+    throw new Error('Payment method required before starting trial');
+  }
+
+  return stripe.subscriptions.create({
+    customer: customerId,
+    items: [{ price: priceId }],
+    trial_period_days: trialDays,
+    payment_settings: {
+      payment_method_types: ['card'],
+      save_default_payment_method: 'on_subscription',
+    },
+    trial_settings: {
+      end_behavior: { missing_payment_method: 'cancel' }, // Auto-cancel if no card at trial end
+    },
+    expand: ['latest_invoice.payment_intent'],
+  });
+}
+
+// Plan change with explicit proration
+async function changePlan(subscriptionId: string, newPriceId: string) {
+  const subscription = await stripe.subscriptions.retrieve(subscriptionId);
+  return stripe.subscriptions.update(subscriptionId, {
+    items: [{ id: subscription.items.data[0].id, price: newPriceId }],
+    proration_behavior: 'always_invoice', // Charge/credit immediately
+    payment_behavior: 'error_if_incomplete', // Fail if upgrade payment fails
+  });
+}
+
+// Dunning webhook — restrict access after payment failure
+app.post('/webhooks/subscription', async (req, res) => {
+  const event = verifyStripeEvent(req);
+
+  switch (event.type) {
+    case 'invoice.payment_failed': {
+      const invoice = event.data.object as Stripe.Invoice;
+      const attempt = invoice.attempt_count;
+      if (attempt >= 3) {
+        // After 3 failed retries, restrict access (don't cancel yet)
+        await userService.setStatus(invoice.customer as string, 'past_due');
+        await emailService.send(invoice.customer_email!, 'payment-failed-final');
+      } else {
+        await emailService.send(invoice.customer_email!, 'payment-failed-retry', { attempt });
+      }
+      break;
+    }
+    case 'customer.subscription.deleted': {
+      const sub = event.data.object as Stripe.Subscription;
+      await userService.deactivate(sub.customer as string);
+      break;
+    }
+  }
+  res.json({ received: true });
+});
+```

package/extensions/ecommerce/skills/tax-compliance.md

@@ -1,117 +1,117 @@
----
-name: "tax-compliance"
-pack: "@rune/ecommerce"
-description: "Tax calculation — sales tax API integration, VAT for EU, digital goods tax, tax-inclusive pricing, audit trail."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# tax-compliance
-
-Tax calculation — sales tax API integration, VAT for EU, digital goods tax, tax-inclusive pricing, audit trail.
-
-#### Workflow
-
-**Step 1 — Detect tax setup**
-Use Grep to find: `tax`, `vat`, `taxjar`, `avalara`, `tax_rate`, `taxAmount`, `tax_exempt`. Check if tax calculation exists and where it happens (cart time vs checkout time).
-
-**Step 2 — Audit tax accuracy**
-Check for:
-- Tax calculated at cart time but not recalculated at checkout (rate may have changed, or user changed shipping address)
-- Hardcoded tax rates instead of API-based calculation (rates change; nexus rules are complex)
-- Missing tax on digital goods (many US states and all EU countries tax digital products)
-- EU VAT: must charge buyer's country VAT rate for B2C digital sales (not seller's country)
-- Tax-inclusive vs tax-exclusive display: must be consistent and clearly labeled
-- No tax audit trail: amounts, rates, and jurisdiction must be stored per order for compliance
-- Missing tax exemption handling (B2B customers with valid VAT number or tax-exempt certificate)
-
-**Step 3 — Emit tax patterns**
-Emit: tax calculation at checkout time (not cart time), API-based rate lookup, EU VAT reverse charge for B2B, and tax audit trail per order line item.
-
-#### Example
-
-```typescript
-// Tax calculation at CHECKOUT time (not cart time) — rates may change
-interface TaxLineItem {
-  productId: string;
-  amount: number;
-  quantity: number;
-  taxCode: string; // Product tax code (e.g., 'txcd_10000000' for general goods)
-}
-
-async function calculateTax(
-  items: TaxLineItem[],
-  shippingAddress: Address,
-  customerTaxExempt: boolean
-): Promise<TaxResult> {
-  if (customerTaxExempt) {
-    return { totalTax: 0, lineItems: items.map(i => ({ ...i, tax: 0, rate: 0 })) };
-  }
-
-  // Use tax API — never hardcode rates
-  const calculation = await stripe.tax.calculations.create({
-    currency: 'usd',
-    line_items: items.map(item => ({
-      amount: item.amount * item.quantity,
-      reference: item.productId,
-      tax_code: item.taxCode,
-    })),
-    customer_details: {
-      address: {
-        line1: shippingAddress.line1,
-        city: shippingAddress.city,
-        state: shippingAddress.state,
-        postal_code: shippingAddress.postalCode,
-        country: shippingAddress.country,
-      },
-      address_source: 'shipping',
-    },
-  });
-
-  return {
-    totalTax: calculation.tax_amount_exclusive,
-    lineItems: calculation.line_items.data.map(li => ({
-      productId: li.reference,
-      tax: li.amount_tax,
-      rate: li.tax_breakdown?.[0]?.rate ?? 0,
-      jurisdiction: li.tax_breakdown?.[0]?.jurisdiction?.display_name ?? 'Unknown',
-    })),
-  };
-}
-
-// EU VAT validation — B2B reverse charge
-async function validateEuVat(vatNumber: string, buyerCountry: string): Promise<boolean> {
-  // Use VIES (VAT Information Exchange System) API
-  const res = await fetch(
-    `https://ec.europa.eu/taxation_customs/vies/rest-api/ms/${buyerCountry}/vat/${vatNumber.replace(/^[A-Z]{2}/, '')}`
-  );
-  const data = await res.json();
-  return data.isValid === true;
-}
-
-// Store tax audit trail per order (required for compliance)
-interface OrderTaxRecord {
-  orderId: string;
-  lineItemId: string;
-  taxAmount: number;
-  taxRate: number;
-  jurisdiction: string;
-  calculatedAt: Date;
-  taxApiTransactionId: string;
-}
-
-// Commit tax record immediately at payment creation — never calculate retroactively
-async function commitTaxRecord(orderId: string, calculation: TaxResult, txnId: string) {
-  await prisma.orderTaxRecord.createMany({
-    data: calculation.lineItems.map(li => ({
-      orderId,
-      lineItemId: li.productId,
-      taxAmount: li.tax,
-      taxRate: li.rate,
-      jurisdiction: li.jurisdiction,
-      calculatedAt: new Date(),
-      taxApiTransactionId: txnId,
-    })),
-  });
-}
-```
+---
+name: "tax-compliance"
+pack: "@rune/ecommerce"
+description: "Tax calculation — sales tax API integration, VAT for EU, digital goods tax, tax-inclusive pricing, audit trail."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# tax-compliance
+
+Tax calculation — sales tax API integration, VAT for EU, digital goods tax, tax-inclusive pricing, audit trail.
+
+#### Workflow
+
+**Step 1 — Detect tax setup**
+Use Grep to find: `tax`, `vat`, `taxjar`, `avalara`, `tax_rate`, `taxAmount`, `tax_exempt`. Check if tax calculation exists and where it happens (cart time vs checkout time).
+
+**Step 2 — Audit tax accuracy**
+Check for:
+- Tax calculated at cart time but not recalculated at checkout (rate may have changed, or user changed shipping address)
+- Hardcoded tax rates instead of API-based calculation (rates change; nexus rules are complex)
+- Missing tax on digital goods (many US states and all EU countries tax digital products)
+- EU VAT: must charge buyer's country VAT rate for B2C digital sales (not seller's country)
+- Tax-inclusive vs tax-exclusive display: must be consistent and clearly labeled
+- No tax audit trail: amounts, rates, and jurisdiction must be stored per order for compliance
+- Missing tax exemption handling (B2B customers with valid VAT number or tax-exempt certificate)
+
+**Step 3 — Emit tax patterns**
+Emit: tax calculation at checkout time (not cart time), API-based rate lookup, EU VAT reverse charge for B2B, and tax audit trail per order line item.
+
+#### Example
+
+```typescript
+// Tax calculation at CHECKOUT time (not cart time) — rates may change
+interface TaxLineItem {
+  productId: string;
+  amount: number;
+  quantity: number;
+  taxCode: string; // Product tax code (e.g., 'txcd_10000000' for general goods)
+}
+
+async function calculateTax(
+  items: TaxLineItem[],
+  shippingAddress: Address,
+  customerTaxExempt: boolean
+): Promise<TaxResult> {
+  if (customerTaxExempt) {
+    return { totalTax: 0, lineItems: items.map(i => ({ ...i, tax: 0, rate: 0 })) };
+  }
+
+  // Use tax API — never hardcode rates
+  const calculation = await stripe.tax.calculations.create({
+    currency: 'usd',
+    line_items: items.map(item => ({
+      amount: item.amount * item.quantity,
+      reference: item.productId,
+      tax_code: item.taxCode,
+    })),
+    customer_details: {
+      address: {
+        line1: shippingAddress.line1,
+        city: shippingAddress.city,
+        state: shippingAddress.state,
+        postal_code: shippingAddress.postalCode,
+        country: shippingAddress.country,
+      },
+      address_source: 'shipping',
+    },
+  });
+
+  return {
+    totalTax: calculation.tax_amount_exclusive,
+    lineItems: calculation.line_items.data.map(li => ({
+      productId: li.reference,
+      tax: li.amount_tax,
+      rate: li.tax_breakdown?.[0]?.rate ?? 0,
+      jurisdiction: li.tax_breakdown?.[0]?.jurisdiction?.display_name ?? 'Unknown',
+    })),
+  };
+}
+
+// EU VAT validation — B2B reverse charge
+async function validateEuVat(vatNumber: string, buyerCountry: string): Promise<boolean> {
+  // Use VIES (VAT Information Exchange System) API
+  const res = await fetch(
+    `https://ec.europa.eu/taxation_customs/vies/rest-api/ms/${buyerCountry}/vat/${vatNumber.replace(/^[A-Z]{2}/, '')}`
+  );
+  const data = await res.json();
+  return data.isValid === true;
+}
+
+// Store tax audit trail per order (required for compliance)
+interface OrderTaxRecord {
+  orderId: string;
+  lineItemId: string;
+  taxAmount: number;
+  taxRate: number;
+  jurisdiction: string;
+  calculatedAt: Date;
+  taxApiTransactionId: string;
+}
+
+// Commit tax record immediately at payment creation — never calculate retroactively
+async function commitTaxRecord(orderId: string, calculation: TaxResult, txnId: string) {
+  await prisma.orderTaxRecord.createMany({
+    data: calculation.lineItems.map(li => ({
+      orderId,
+      lineItemId: li.productId,
+      taxAmount: li.tax,
+      taxRate: li.rate,
+      jurisdiction: li.jurisdiction,
+      calculatedAt: new Date(),
+      taxApiTransactionId: txnId,
+    })),
+  });
+}
+```