@folpe/loom 0.1.0 → 0.2.0

package/data/skills/cli-development/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: cli-development
+description: "CLI tool development patterns for Node.js with Commander.js, terminal UX, and npm distribution. Use when building command-line tools."
+allowed-tools: "Read, Write, Edit, Glob, Grep"
+---
+
+# CLI Development Patterns
+
+## Project Structure
+
+```
+src/
+  index.ts          # Entry point — program definition and parse()
+  commands/         # One file per command/subcommand
+    init.ts
+    build.ts
+    list.ts
+  lib/              # Shared utilities
+    config.ts       # Config loading and validation
+    output.ts       # Formatting and printing helpers
+    errors.ts       # Custom error classes
+```
+
+## Commander.js Setup
+
+- Define the program with metadata from `package.json`:
+  ```ts
+  const program = new Command()
+    .name('mytool')
+    .description('What this tool does')
+    .version(version)
+  ```
+- One file per subcommand — register with `program.addCommand()`.
+- Use `.argument()` for required positional args, `.option()` for flags:
+  ```ts
+  program
+    .command('init')
+    .description('Initialize a new project')
+    .argument('<name>', 'project name')
+    .option('-t, --template <template>', 'template to use', 'default')
+    .action(async (name, options) => { /* ... */ })
+  ```
+- Always provide `--help` descriptions for all arguments and options.
+
+## Exit Codes
+
+- `0` — success
+- `1` — general error (runtime failure, unhandled exception)
+- `2` — usage error (invalid arguments, missing required flags)
+- Exit explicitly: `process.exit(code)` after cleanup.
+- Catch unhandled errors at the top level:
+  ```ts
+  program.parseAsync().catch((error) => {
+    console.error(error.message)
+    process.exit(1)
+  })
+  ```
+
+## Output Conventions
+
+- Use `stdout` for actual output (data, results, formatted tables).
+- Use `stderr` for progress, logging, warnings, and errors.
+- Support `--json` flag for machine-readable output on data commands.
+- Support `--quiet` or `--silent` flag to suppress non-essential output.
+- Use colors sparingly — respect `NO_COLOR` environment variable:
+  ```ts
+  const useColor = !process.env.NO_COLOR && process.stdout.isTTY
+  ```
+
+## Terminal UX
+
+- Show a spinner for long operations (use `ora` or `nanospinner`).
+- Use progress bars for multi-step or percentage-based operations.
+- Confirm destructive actions with a prompt (use `@inquirer/prompts`):
+  ```ts
+  const confirmed = await confirm({ message: 'Delete all files?' })
+  if (!confirmed) process.exit(0)
+  ```
+- Use tables for structured data display (use `cli-table3` or `columnify`).
+- Truncate long output with `--limit` option or pipe to `less`.
+
+## Input
+
+- Accept input from stdin for piping:
+  ```ts
+  if (!process.stdin.isTTY) {
+    const input = await readStdin()
+  }
+  ```
+- Support both `--flag value` and `--flag=value` syntax (Commander.js handles this).
+- Use environment variables as fallback for configuration: `MYTOOL_TOKEN`, `MYTOOL_CONFIG`.
+
+## Error Messages
+
+- Include what went wrong, why, and how to fix it:
+  ```
+  Error: Config file not found at ./config.yaml
+  Run `mytool init` to create a default configuration.
+  ```
+- Use chalk/picocolors for error formatting:
+  - Red for errors
+  - Yellow for warnings
+  - Dim for secondary info
+- Never show raw stack traces to users. Log them with `--verbose` flag.
+
+## Configuration
+
+- Support config file (`.mytoolrc`, `mytool.config.ts`, or field in `package.json`).
+- Use `cosmiconfig` or manual lookup for config file discovery.
+- Validate config with Zod schema — fail fast with clear error on invalid config.
+- Allow CLI flags to override config file values.
+
+## Bundling & Distribution
+
+- Bundle with `tsup` for a single distributable file:
+  ```ts
+  // tsup.config.ts
+  export default defineConfig({
+    entry: ['src/index.ts'],
+    format: ['esm'],
+    target: 'node20',
+    clean: true,
+    banner: { js: '#!/usr/bin/env node' },
+  })
+  ```
+- Set `"bin"` in `package.json` pointing to the built file.
+- Set `"type": "module"` for ESM.
+- Test the built binary locally before publishing: `node dist/index.js`.
+
+## Testing
+
+- Test commands by invoking them programmatically, not by spawning processes:
+  ```ts
+  import { program } from '../src/index'
+  program.parse(['node', 'test', 'init', 'my-project'])
+  ```
+- Test output by capturing stdout/stderr.
+- Test error cases: missing args, invalid flags, missing config.
+- Test stdin piping with mock readable streams.

package/data/skills/react-native-patterns/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: react-native-patterns
+description: "React Native and Expo best practices for navigation, styling, performance, and native features. Use when building mobile apps with Expo. Inspired by callstackincubator/agent-skills and expo/skills."
+allowed-tools: "Read, Write, Edit, Glob, Grep"
+---
+
+# React Native & Expo Patterns
+
+## Expo Router
+
+- Use file-based routing in the `app/` directory exclusively.
+- Never co-locate components, types, or utilities in the `app/` directory — keep them in `src/`.
+- Always ensure a route matches `/` (may be inside a group route).
+- Use layout routes (`_layout.tsx`) for shared navigation UI (tabs, stacks, drawers).
+- Remove old route files immediately when restructuring navigation.
+- Use kebab-case for file names: `comment-card.tsx`.
+
+## Styling with NativeWind
+
+- Use NativeWind (Tailwind for React Native) as the primary styling method.
+- Use `className` prop like web Tailwind — NativeWind compiles to StyleSheet.
+- Use `cn()` helper for conditional classes.
+- Prefer `useWindowDimensions` over `Dimensions.get()` for responsive layouts.
+- Use flexbox exclusively for layout — avoid absolute positioning except for overlays.
+
+## Running the App
+
+- **Always try Expo Go first** before creating custom builds (`npx expo start`).
+- Only use `npx expo run:ios/android` when custom native modules are required.
+- Expo Go supports: all `expo-*` packages, Expo Router, Reanimated, Gesture Handler.
+
+## Components
+
+- Use functional components only — never class components.
+- Use `expo-image` instead of React Native's `Image` — better caching and performance.
+- Use `expo-image` with `source="sf:name"` for SF Symbols icons — not `@expo/vector-icons`.
+- Use `react-native-safe-area-context` — never React Native's built-in `SafeAreaView`.
+- Use `<ScrollView contentInsetAdjustmentBehavior="automatic" />` instead of `<SafeAreaView>` for root scrolling.
+- Use `process.env.EXPO_OS` instead of `Platform.OS`.
+- Use `React.use` instead of `React.useContext`.
+
+## Navigation
+
+- Use Expo Router's typed routes for type-safe navigation.
+- Handle deep linking and universal links from project start.
+- Use native tabs (`NativeTabs`) for iOS tab navigation when possible.
+- Preload frequently accessed screens for faster navigation.
+
+## Performance
+
+- **Profile before optimizing** — measure with React DevTools and Xcode Instruments.
+- Replace `ScrollView` with `FlashList` (not `FlatList`) for large lists.
+- Use React Compiler for automatic memoization when available.
+- Avoid barrel exports — import directly from source files to reduce bundle size.
+- Keep JS thread work minimal — offload to native with Turbo Modules when needed.
+- Target 60fps — never block the JS thread with heavy computation.
+- Use `useDeferredValue` for expensive computations during rendering.
+
+## Animations
+
+- Use `react-native-reanimated` for performant animations on the UI thread.
+- Animate only `transform` and `opacity` — avoid animating layout properties.
+- Use shared values and worklets for gesture-driven animations.
+- Respect `prefers-reduced-motion` accessibility setting.
+
+## Offline & Storage
+
+- Use `@react-native-async-storage/async-storage` or `react-native-mmkv` for local key-value storage.
+- Use `expo-sqlite` for structured offline data.
+- Implement optimistic updates for network operations.
+- Cache critical data locally for offline-first experience.
+
+## Push Notifications
+
+- Use `expo-notifications` for push notification setup.
+- Request permission at a contextual moment — never on first launch.
+- Handle notification responses (tap, dismiss) in the app root.
+- Store push tokens in your backend database, linked to user profiles.
+
+## App Distribution
+
+- Use EAS Build for creating production builds.
+- Use EAS Submit for app store submissions.
+- Configure `app.json` / `app.config.ts` thoroughly: icons, splash, permissions, version.
+- Test on both iOS and Android — never assume platform parity.

package/data/skills/seo-optimization/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: seo-optimization
+description: "SEO best practices for structured data, meta tags, Core Web Vitals, and indexing. Use when building landing pages, marketing sites, or public-facing content."
+allowed-tools: "Read, Write, Edit, Glob, Grep"
+---
+
+# SEO Optimization
+
+## Meta Tags
+
+- Every page must have unique `title` and `description` meta tags:
+  ```ts
+  export const metadata: Metadata = {
+    title: 'Product Name — Clear Value Proposition',
+    description: 'Compelling 150-160 char description with primary keyword and call to action.',
+  }
+  ```
+- Title format: `Page Title — Brand Name` (50-60 characters).
+- Description: 150-160 characters, include primary keyword, end with CTA or benefit.
+- Use `generateMetadata()` for dynamic routes to generate unique meta per page.
+
+## Open Graph & Social
+
+- Include Open Graph tags for social sharing:
+  ```ts
+  openGraph: {
+    title: 'Page Title',
+    description: 'Social description',
+    images: [{ url: '/og-image.png', width: 1200, height: 630 }],
+    type: 'website',
+  }
+  ```
+- Create a dedicated OG image for each important page (1200x630px).
+- Add Twitter card meta: `twitter: { card: 'summary_large_image' }`.
+
+## Structured Data (JSON-LD)
+
+- Add JSON-LD structured data for rich search results:
+  ```tsx
+  <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify({
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name: product.name,
+    description: product.description,
+    offers: { '@type': 'Offer', price: product.price, priceCurrency: 'EUR' }
+  }) }} />
+  ```
+- Use appropriate schema types: `Organization`, `Product`, `Article`, `FAQPage`, `BreadcrumbList`.
+- Validate with Google's Rich Results Test.
+
+## Semantic HTML
+
+- Use proper heading hierarchy: one `<h1>` per page, then `<h2>`, `<h3>`, etc.
+- Use semantic elements: `<main>`, `<article>`, `<section>`, `<nav>`, `<aside>`, `<footer>`.
+- Add `alt` text to all images — descriptive, not keyword-stuffed.
+- Use `<a>` with descriptive anchor text — avoid "click here".
+
+## Performance (Core Web Vitals)
+
+- Target scores: LCP < 2.5s, INP < 200ms, CLS < 0.1.
+- Optimize images with `next/image`: proper sizing, modern formats (WebP/AVIF), lazy loading.
+- Minimize render-blocking resources: defer non-critical CSS/JS.
+- Use `next/font` to prevent FOUT/FOIT.
+- Preload critical assets: hero images, above-the-fold fonts.
+
+## Technical SEO
+
+- Generate `sitemap.xml` dynamically:
+  ```ts
+  // src/app/sitemap.ts
+  export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+    return [
+      { url: 'https://example.com', lastModified: new Date(), changeFrequency: 'weekly', priority: 1 },
+    ]
+  }
+  ```
+- Create `robots.txt`:
+  ```ts
+  // src/app/robots.ts
+  export default function robots(): MetadataRoute.Robots {
+    return { rules: { userAgent: '*', allow: '/' }, sitemap: 'https://example.com/sitemap.xml' }
+  }
+  ```
+- Use canonical URLs to prevent duplicate content issues.
+- Implement proper redirects (301) for moved pages — never soft 404s.
+
+## Content
+
+- Place primary keyword in the first 100 words of page content.
+- Use internal links between related pages to distribute page authority.
+- Add breadcrumb navigation with `BreadcrumbList` schema.
+- Ensure all pages are reachable within 3 clicks from the homepage.
+
+## Internationalization
+
+- Use `hreflang` tags for multi-language sites.
+- Use `lang` attribute on `<html>` element.
+- Create dedicated URLs per language: `/en/about`, `/fr/about`.

package/data/skills/shadcn-ui/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: shadcn-ui
+description: "ShadCN UI component patterns, composition, and accessibility guidelines. Use when building interfaces with ShadCN components. Inspired by ibelick/ui-skills baseline-ui."
+allowed-tools: "Read, Write, Edit, Glob, Grep"
+---
+
+# ShadCN UI Patterns
+
+## Installation & Setup
+
+- Install components individually with `npx shadcn@latest add <component>` — never install all at once.
+- Components are copied to `src/components/ui/` — they are yours to customize.
+- Configure `components.json` for path aliases and styling preferences.
+- Use `cn()` from `src/lib/utils` for class merging (clsx + tailwind-merge).
+
+## Component Usage
+
+- **Always use ShadCN primitives** before building custom components:
+  - `Button` for all clickable actions (with appropriate `variant` and `size`)
+  - `Card` for content containers
+  - `Dialog` for modal overlays
+  - `Sheet` for slide-out panels
+  - `DropdownMenu` for action menus
+  - `Select` for option picking
+  - `Table` for data display
+  - `Form` + `Input` + `Label` for forms
+  - `Badge` for tags and status indicators
+  - `Tabs` for content switching
+  - `Toast` / `Sonner` for notifications
+- Never rebuild keyboard or focus behavior by hand — use the component primitives.
+- Never mix primitive systems (Radix, Headless UI, React Aria) within the same surface.
+
+## Forms
+
+- Use `react-hook-form` + `zod` with ShadCN's `Form` component:
+  ```tsx
+  const form = useForm<z.infer<typeof schema>>({
+    resolver: zodResolver(schema),
+    defaultValues: { name: '' },
+  })
+  ```
+- Stack form fields with `space-y-4`.
+- Use `grid gap-4 md:grid-cols-2` for side-by-side fields on desktop.
+- Show validation errors inline with `FormMessage`.
+- Use `FormDescription` for helper text below fields.
+
+## Data Tables
+
+- Use ShadCN `DataTable` pattern with `@tanstack/react-table`:
+  - Define columns with type-safe `ColumnDef`.
+  - Support sorting, filtering, and pagination.
+  - Add row actions via `DropdownMenu`.
+- Use `tabular-nums` on numeric columns for alignment.
+- Add loading skeletons with ShadCN `Skeleton` for async data.
+
+## Dialogs & Alerts
+
+- Use `Dialog` for informational or form-based modals.
+- Use `AlertDialog` for destructive or irreversible actions — never a plain `Dialog`.
+- Keep dialog content focused — one primary action per dialog.
+- Always provide a way to dismiss (close button, escape key, outside click).
+
+## Theming
+
+- Use CSS variables from the ShadCN theme system: `bg-background`, `text-foreground`, `bg-card`, `text-muted-foreground`, `bg-primary`, etc.
+- Never hardcode hex colors — always use semantic tokens.
+- Support dark mode via the `dark` class on `<html>` — CSS variables handle the switch.
+- Limit accent color usage to one per view.
+
+## Accessibility
+
+- All icon-only buttons must have `aria-label`.
+- Use `sr-only` class for screen-reader-only text.
+- Ensure all interactive elements have visible focus states (ShadCN handles this by default).
+- Use `role` and `aria-*` attributes when composing custom components.
+- Never block paste in `input` or `textarea` elements.
+
+## Animation
+
+- Never add animation unless explicitly requested.
+- Use `transition-colors` for hover/focus state changes.
+- Keep interaction feedback under 200ms.
+- Avoid animating layout properties (`width`, `height`, `margin`, `padding`) — use `transform` and `opacity` only.
+- Respect `prefers-reduced-motion` media query.
+
+## Anti-Patterns to Avoid
+
+- Never use `h-screen` — use `h-dvh` for correct mobile viewport.
+- Never use arbitrary `z-index` values — use a fixed scale.
+- Never use gradients or glow effects unless explicitly requested.
+- Never use custom easing curves unless explicitly requested.
+- Empty states must have one clear next action.

package/data/skills/stripe-integration/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: stripe-integration
+description: "Stripe payment integration patterns for checkout, subscriptions, and webhooks. Use when building e-commerce, SaaS billing, or any payment flow."
+allowed-tools: "Read, Write, Edit, Glob, Grep"
+---
+
+# Stripe Integration
+
+## Setup
+
+- Install `stripe` (server) and `@stripe/stripe-js` + `@stripe/react-stripe-js` (client).
+- Store keys in environment variables:
+  - `STRIPE_SECRET_KEY` — server-side only, never expose to client
+  - `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` — safe for client-side
+  - `STRIPE_WEBHOOK_SECRET` — for verifying webhook signatures
+- Create a Stripe instance in `src/lib/stripe.ts`:
+  ```ts
+  import Stripe from 'stripe'
+  export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
+  ```
+
+## Checkout
+
+- **Always use Stripe Checkout or Payment Elements** — never collect card details directly.
+- Create a Checkout Session server-side, redirect client-side:
+  ```ts
+  const session = await stripe.checkout.sessions.create({
+    mode: 'payment', // or 'subscription'
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: `${origin}/success?session_id={CHECKOUT_SESSION_ID}`,
+    cancel_url: `${origin}/cart`,
+    metadata: { userId, orderId },
+  })
+  ```
+- Use `metadata` to link Stripe objects back to your database records.
+- For subscriptions, use `mode: 'subscription'` with recurring prices.
+
+## Webhooks
+
+- Create a webhook endpoint at `/api/webhooks/stripe`:
+  ```ts
+  const sig = request.headers.get('stripe-signature')!
+  const event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!)
+  ```
+- Always verify webhook signatures. Never trust unverified payloads.
+- Handle these critical events:
+  - `checkout.session.completed` — fulfill the order
+  - `invoice.payment_succeeded` — extend subscription
+  - `invoice.payment_failed` — notify user, retry logic
+  - `customer.subscription.deleted` — revoke access
+- Make webhook handlers idempotent — the same event may arrive multiple times.
+- Return 200 quickly. Process heavy logic asynchronously if needed.
+
+## Products & Prices
+
+- Define products and prices in Stripe Dashboard for simplicity.
+- Use `price` IDs (not `product` IDs) when creating Checkout Sessions.
+- For multiple pricing tiers, create one product with multiple prices (monthly/yearly).
+- Sync product/price data to your database via webhooks or a scheduled job.
+
+## Customer Portal
+
+- Use Stripe Customer Portal for subscription management (upgrade, downgrade, cancel, update payment method).
+- Create a portal session and redirect:
+  ```ts
+  const portalSession = await stripe.billingPortal.sessions.create({
+    customer: customerId,
+    return_url: `${origin}/account`,
+  })
+  ```
+
+## Security
+
+- Never log or store raw card numbers, CVV, or full card details.
+- Use Stripe's PCI-compliant elements for all card input.
+- Validate amounts and currencies server-side before creating charges.
+- Use `idempotencyKey` for critical operations to prevent duplicate charges.
+- Restrict Stripe API key permissions in production (read-only where possible).
+
+## Testing
+
+- Use Stripe test mode keys during development.
+- Use test card numbers: `4242424242424242` (success), `4000000000000002` (decline).
+- Use Stripe CLI to forward webhooks to localhost:
+  ```bash
+  stripe listen --forward-to localhost:3000/api/webhooks/stripe
+  ```
+- Test all webhook event types, especially failure scenarios.

package/data/skills/supabase-patterns/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: supabase-patterns
+description: "Supabase best practices for auth, database, RLS, and real-time. Use when working with Supabase in any project. Inspired by supabase/agent-skills."
+allowed-tools: "Read, Write, Edit, Glob, Grep"
+---
+
+# Supabase Patterns
+
+## Authentication
+
+- Use `@supabase/ssr` for Next.js server-side auth — never use `@supabase/auth-helpers-nextjs` (deprecated).
+- Create two client helpers:
+  - `createClient()` in `src/lib/supabase/client.ts` for Client Components
+  - `createServerClient()` in `src/lib/supabase/server.ts` for Server Components / Actions
+- Always validate session server-side before granting access. Never trust `supabase.auth.getUser()` from the client alone.
+- Use middleware (`middleware.ts`) to refresh the session on every request:
+  ```ts
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user && protectedRoutes.includes(request.nextUrl.pathname)) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+  ```
+- Support multiple auth strategies: email/password, OAuth (Google, GitHub), magic link.
+- Store user metadata in a separate `profiles` table linked by `auth.users.id`.
+
+## Row Level Security (RLS)
+
+- **Enable RLS on every table** — no exceptions, even internal tables.
+- Write policies that reference `auth.uid()` directly:
+  ```sql
+  CREATE POLICY "Users read own data"
+    ON profiles FOR SELECT
+    USING (auth.uid() = user_id);
+  ```
+- Avoid `security definer` functions unless absolutely necessary. Prefer RLS policies.
+- Test policies explicitly: try accessing data as different users/roles.
+- Use `auth.jwt() ->> 'role'` for role-based access if implementing RBAC.
+
+## Database Schema
+
+- Use `uuid` for primary keys, generated by `gen_random_uuid()`.
+- Add `created_at` and `updated_at` timestamps to every table:
+  ```sql
+  created_at timestamptz DEFAULT now() NOT NULL,
+  updated_at timestamptz DEFAULT now() NOT NULL
+  ```
+- Create an `updated_at` trigger using `moddatetime` extension.
+- Use foreign key constraints for referential integrity.
+- Add indexes on columns used in WHERE clauses and JOIN conditions.
+
+## Query Patterns
+
+- Use the Supabase client query builder for simple CRUD:
+  ```ts
+  const { data, error } = await supabase
+    .from('posts')
+    .select('*, author:profiles(name, avatar_url)')
+    .eq('published', true)
+    .order('created_at', { ascending: false })
+    .limit(20)
+  ```
+- Handle errors explicitly — never ignore `error`:
+  ```ts
+  if (error) throw new Error(error.message)
+  ```
+- Use `.single()` when expecting exactly one row. Use `.maybeSingle()` when the row may not exist.
+- Use server-side Supabase client for mutations in Server Actions.
+
+## Real-time
+
+- Use Supabase Realtime only for features that genuinely need live updates (chat, notifications, collaboration).
+- Subscribe in Client Components and clean up on unmount:
+  ```ts
+  useEffect(() => {
+    const channel = supabase.channel('room').on('postgres_changes', { event: '*', schema: 'public', table: 'messages' }, handler).subscribe()
+    return () => { supabase.removeChannel(channel) }
+  }, [])
+  ```
+- Prefer polling or revalidation for data that changes infrequently.
+
+## Storage
+
+- Use Supabase Storage for file uploads (images, documents).
+- Create separate buckets for public vs private files.
+- Set RLS policies on storage buckets.
+- Generate signed URLs for private files with short expiration times.
+
+## Performance
+
+- Use connection pooling (Supavisor) in production — never connect directly at scale.
+- Add `LIMIT` to all queries. Never fetch unbounded result sets.
+- Use `select('column1, column2')` instead of `select('*')` for large tables.
+- Create partial indexes for frequently filtered subsets of data.