@folpe/loom 0.1.0 → 0.3.0

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

@@ -0,0 +1,147 @@
+---
+name: cli-development
+description: "CLI tool development patterns for Node.js with Commander.js, terminal UX, error handling, and npm distribution. Use when building command-line tools, adding CLI commands, implementing terminal prompts, or bundling CLI binaries for distribution."
+---
+
+# CLI Development Patterns
+
+## Critical Rules
+
+- **Use `stdout` for data, `stderr` for logs** — never mix output channels.
+- **Exit with proper codes** — `0` success, `1` runtime error, `2` usage error.
+- **Never show raw stack traces** — log them with `--verbose` flag only.
+- **Respect `NO_COLOR`** — check `process.env.NO_COLOR` before using colors.
+- **Validate config with Zod** — fail fast with clear error on invalid config.
+- **Confirm destructive actions** — always prompt before irreversible operations.
+
+## 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` or `@clack/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/drizzle-patterns/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: drizzle-patterns
+description: "Drizzle ORM patterns for schema design, migrations, transactions, and DAO functions. Use when creating database schemas, writing queries, implementing transactions, or working with PostgreSQL via Drizzle."
+---
+
+# Drizzle ORM Patterns
+
+## Critical Rules
+
+- **Infer types from schema** — never duplicate type definitions manually.
+- **Use `limit()` on all queries** — never fetch unbounded result sets.
+- **Select only needed columns** — avoid `select()` with no arguments on large tables.
+- **Never nest transactions** — keep transactions short with no external API calls inside.
+- **Never edit generated migration files** — review SQL before applying in production.
+- **Add indexes** on columns used in `WHERE`, `JOIN`, and `ORDER BY`.
+
+## Schema Design
+
+- Define schemas in `src/schema/` with one file per entity.
+- Export all tables from `src/schema/index.ts` barrel file.
+- Use `pgTable` for table definitions with typed columns.
+
+```ts
+// src/schema/user.ts
+import { pgTable, uuid, text, timestamp, boolean } from "drizzle-orm/pg-core";
+
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  email: text("email").notNull().unique(),
+  name: text("name").notNull(),
+  role: text("role", { enum: ["USER", "ADMIN"] }).notNull().default("USER"),
+  emailVerified: boolean("email_verified").notNull().default(false),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+});
+```
+
+## Relations
+
+- Define relations separately using `relations()`:
+
+```ts
+import { relations } from "drizzle-orm";
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+  organizations: many(organizationMembers),
+}));
+
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, { fields: [posts.authorId], references: [users.id] }),
+}));
+```
+
+## Database Client
+
+```ts
+// src/lib/db.ts
+import { drizzle } from "drizzle-orm/node-postgres";
+import * as schema from "@/schema";
+
+export const db = drizzle(process.env.DATABASE_URL!, { schema });
+```
+
+## Query Patterns
+
+- Use the query builder for complex reads:
+```ts
+const result = await db.query.users.findMany({
+  where: eq(users.role, "ADMIN"),
+  with: { posts: true },
+  orderBy: [desc(users.createdAt)],
+  limit: 20,
+});
+```
+
+- Use `select()` for simple reads with specific columns:
+```ts
+const result = await db.select({
+  id: users.id,
+  name: users.name,
+}).from(users).where(eq(users.role, "ADMIN"));
+```
+
+## Transactions
+
+- Wrap multi-table writes in transactions:
+```ts
+await db.transaction(async (tx) => {
+  const [org] = await tx.insert(organizations).values({ name }).returning();
+  await tx.insert(organizationMembers).values({
+    organizationId: org.id,
+    userId: currentUser.id,
+    role: "OWNER",
+  });
+});
+```
+
+## DAO Pattern
+
+- Create DAO functions in `src/dal/` for reusable queries:
+
+```ts
+// src/dal/user.dal.ts
+export async function findUserById(id: string) {
+  return db.query.users.findFirst({
+    where: eq(users.id, id),
+  });
+}
+
+export async function findUsersByOrg(orgId: string) {
+  return db.select()
+    .from(users)
+    .innerJoin(orgMembers, eq(orgMembers.userId, users.id))
+    .where(eq(orgMembers.orgId, orgId));
+}
+
+export async function createUser(data: NewUser) {
+  const [user] = await db.insert(users).values(data).returning();
+  return user;
+}
+
+export async function updateUser(id: string, data: Partial<NewUser>) {
+  const [user] = await db.update(users)
+    .set({ ...data, updatedAt: new Date() })
+    .where(eq(users.id, id))
+    .returning();
+  return user;
+}
+
+export async function deleteUser(id: string) {
+  await db.delete(users).where(eq(users.id, id));
+}
+```
+
+## Migrations
+
+- Generate migrations with `npx drizzle-kit generate`.
+- Apply with `npx drizzle-kit migrate`.
+- Use `drizzle-kit push` only in development for quick iteration.
+- Review generated SQL before applying in production.
+
+## Type Inference
+
+```ts
+import type { InferSelectModel, InferInsertModel } from "drizzle-orm";
+
+export type User = InferSelectModel<typeof users>;
+export type NewUser = InferInsertModel<typeof users>;
+```
+
+## Performance
+
+- Add indexes on columns used in `WHERE`, `JOIN`, and `ORDER BY`:
+```ts
+import { index } from "drizzle-orm/pg-core";
+
+export const posts = pgTable("posts", {
+  // columns...
+}, (table) => [
+  index("posts_author_idx").on(table.authorId),
+  index("posts_created_at_idx").on(table.createdAt),
+]);
+```
+
+- Use `prepare()` for frequently executed queries.

package/data/skills/env-validation/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: env-validation
+description: "Environment variable validation with Zod schemas and type-safe access. Use when configuring environment variables, adding new secrets, or setting up project configuration."
+---
+
+# Environment Variable Validation
+
+## Critical Rules
+
+- **Validate at startup** — crash early if env vars are missing/invalid.
+- **Single source of truth** — `src/env.ts` is the only place to access env vars.
+- **Never use `process.env` directly** — always import from `@/env`.
+- **Type-safe prefixes** — validate format (e.g., `startsWith("sk_")` for Stripe keys).
+- **Maintain `.env.example`** — document all required variables without values.
+- **Never commit secrets** — `.env.local` and `.env.production` are gitignored.
+
+## Schema Definition
+
+Validate all environment variables at startup with a Zod schema:
+
+```ts
+// src/env.ts
+import { z } from "zod";
+
+const envSchema = z.object({
+  // Database
+  DATABASE_URL: z.string().url(),
+
+  // Auth
+  BETTER_AUTH_SECRET: z.string().min(32),
+  BETTER_AUTH_URL: z.string().url(),
+
+  // Email
+  RESEND_API_KEY: z.string().startsWith("re_"),
+
+  // Stripe
+  STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
+  STRIPE_WEBHOOK_SECRET: z.string().startsWith("whsec_"),
+  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith("pk_"),
+
+  // App
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
+});
+
+export const env = envSchema.parse(process.env);
+```
+
+## Usage
+
+Always import from `@/env` — never access `process.env` directly:
+
+```ts
+// Good
+import { env } from "@/env";
+const db = drizzle(env.DATABASE_URL);
+
+// Bad — unvalidated, untyped
+const db = drizzle(process.env.DATABASE_URL!);
+```
+
+## Client-Side Variables
+
+Only `NEXT_PUBLIC_` prefixed variables are available in the browser:
+
+```ts
+// src/env.ts
+const clientSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith("pk_"),
+});
+
+const serverSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  BETTER_AUTH_SECRET: z.string().min(32),
+  RESEND_API_KEY: z.string().startsWith("re_"),
+  // ...server-only vars
+});
+
+// Merge for full validation
+const envSchema = serverSchema.merge(clientSchema);
+
+export const env = envSchema.parse(process.env);
+
+// Client-only export for safe use in client components
+export const clientEnv = clientSchema.parse({
+  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
+});
+```
+
+## .env Files
+
+```
+.env                  # Shared defaults (committed)
+.env.local            # Local overrides (gitignored)
+.env.development      # Dev-specific
+.env.production       # Prod-specific (gitignored)
+.env.test             # Test-specific
+```
+
+### .env.example
+
+Maintain a `.env.example` with all required variables (no values):
+
+```env
+# Database
+DATABASE_URL=
+
+# Auth
+BETTER_AUTH_SECRET=
+BETTER_AUTH_URL=
+
+# Email
+RESEND_API_KEY=
+
+# Stripe
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
+
+# App
+NEXT_PUBLIC_APP_URL=
+```
+
+## Startup Validation
+
+The `env.ts` import triggers validation. Import it early in your app:
+
+```ts
+// src/app/layout.tsx
+import "@/env"; // Validates env vars at startup
+```
+
+If validation fails, the app crashes immediately with a clear error:
+
+```
+ZodError: [
+  { path: ["DATABASE_URL"], message: "Required" },
+  { path: ["RESEND_API_KEY"], message: "Invalid" }
+]
+```

package/data/skills/form-validation/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: form-validation
+description: "Zod dual validation patterns for client and server with react-hook-form and ShadCN Form. Use when building forms, implementing validation, or creating input schemas with i18n error messages."
+---
+
+# Form Validation Patterns
+
+## Critical Rules
+
+- **One Zod schema, two validations** — share between client and server.
+- **Schema files in `src/schemas/`** — never inline schemas in components.
+- **Use ShadCN Form components** — `FormField`, `FormMessage` for consistent UX.
+- **Always show inline errors** — next to the field, not in toasts.
+- **Disable submit while pending** — prevent double submissions.
+- **Default values required** — every field needs a `defaultValues` entry in useForm.
+
+## Dual Validation Strategy
+
+Every form must validate on **both client and server**:
+- **Client**: instant feedback, UX quality.
+- **Server**: security, data integrity — never trust client validation alone.
+
+Use a single Zod schema shared between client and server.
+
+## Shared Schema Definition
+
+```ts
+// src/schemas/user.schema.ts
+import { z } from "zod";
+
+export const createUserSchema = z.object({
+  name: z.string().min(2, "Name must be at least 2 characters").max(100),
+  email: z.string().email("Invalid email address"),
+  role: z.enum(["USER", "ADMIN"]).default("USER"),
+  bio: z.string().max(500).optional(),
+});
+
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+```
+
+## Client-Side Validation with react-hook-form
+
+```tsx
+"use client";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { createUserSchema, type CreateUserInput } from "@/schemas/user.schema";
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+
+export function CreateUserForm() {
+  const form = useForm<CreateUserInput>({
+    resolver: zodResolver(createUserSchema),
+    defaultValues: { name: "", email: "", role: "USER" },
+  });
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Name</FormLabel>
+              <FormControl><Input {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        {/* More fields... */}
+        <Button type="submit" disabled={form.formState.isSubmitting}>
+          Create
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+## Server-Side Validation
+
+```ts
+// src/actions/user.actions.ts
+"use server";
+import { createUserSchema } from "@/schemas/user.schema";
+
+export async function createUser(input: unknown) {
+  const parsed = createUserSchema.safeParse(input);
+  if (!parsed.success) {
+    return { success: false, error: parsed.error.errors[0].message };
+  }
+  // proceed with validated data...
+}
+```
+
+## I18n Error Messages with Zod
+
+For internationalized error messages, use a Zod error map:
+
+```ts
+// src/lib/zod-i18n.ts
+import { z } from "zod";
+import { getTranslations } from "next-intl/server";
+
+export async function createI18nSchema() {
+  const t = await getTranslations("validation");
+
+  return {
+    createUser: z.object({
+      name: z.string().min(2, t("name.min", { min: 2 })),
+      email: z.string().email(t("email.invalid")),
+    }),
+  };
+}
+```
+
+Or use a custom error map:
+
+```ts
+// src/lib/zod-error-map.ts
+import { type ZodErrorMap, ZodIssueCode } from "zod";
+
+export function createZodErrorMap(t: (key: string, params?: Record<string, unknown>) => string): ZodErrorMap {
+  return (issue, ctx) => {
+    switch (issue.code) {
+      case ZodIssueCode.too_small:
+        return { message: t("too_small", { minimum: issue.minimum }) };
+      case ZodIssueCode.too_big:
+        return { message: t("too_big", { maximum: issue.maximum }) };
+      case ZodIssueCode.invalid_string:
+        if (issue.validation === "email") return { message: t("invalid_email") };
+        break;
+    }
+    return { message: ctx.defaultError };
+  };
+}
+```
+
+## Multi-Card Form Layout
+
+For complex forms, split into logical sections using Cards:
+
+```tsx
+<form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+  <Card>
+    <CardHeader>
+      <CardTitle>Personal Information</CardTitle>
+    </CardHeader>
+    <CardContent className="grid gap-4 md:grid-cols-2">
+      {/* Name, Email fields */}
+    </CardContent>
+  </Card>
+
+  <Card>
+    <CardHeader>
+      <CardTitle>Preferences</CardTitle>
+    </CardHeader>
+    <CardContent className="space-y-4">
+      {/* Role, Bio fields */}
+    </CardContent>
+  </Card>
+
+  <div className="flex justify-end">
+    <Button type="submit">Create User</Button>
+  </div>
+</form>
+```

package/data/skills/hero-copywriting/SKILL.md

@@ -1,14 +1,22 @@
 ---
 name: hero-copywriting
-description: "Guidelines for writing high-converting hero sections. Use when creating landing pages, marketing pages, or any page with a hero section."
-allowed-tools: "Read, Write, Edit"
+description: "Guidelines for writing high-converting hero sections with headlines, CTAs, and social proof. Use when creating landing pages, writing marketing copy, designing hero sections, or building any page that needs a compelling above-the-fold area."
 ---
 
 # Hero Section Copywriting
 
+## Critical Rules
+
+- **Lead with the outcome, not the feature** — what does the user GET?
+- **Headlines must be 8-12 words maximum** — short, punchy, outcome-focused.
+- **CTA must use action verbs** — "Start", "Get", "Try", "Launch", "Build".
+- **Always include social proof** — logos, metrics, ratings, or testimonials.
+- **Be specific over generic** — "Save 5 hours a week" beats "Save time".
+- **Speak to the reader directly** — use "you" and "your".
+
 ## Headline Rules
 
-- **Lead with the outcome**, not the feature. What does the user GET?
+- Lead with the outcome, not the feature. What does the user GET?
   - Bad: "AI-powered project management"
   - Good: "Ship projects 3x faster with your AI co-pilot"
 - Keep headlines to **8-12 words maximum**.
@@ -41,7 +49,7 @@ allowed-tools: "Read, Write, Edit"
 
 ## Visual Guidelines
 
-- Hero should occupy the full viewport height on desktop (`min-h-screen` or `min-h-[80vh]`).
+- Hero should occupy the full viewport height on desktop (`min-h-dvh` or `min-h-[80vh]`).
 - Text should be left-aligned or center-aligned. Never justify.
 - Maximum content width: `max-w-2xl` for centered, `max-w-xl` for left-aligned.
 - Generous whitespace. Don't crowd the hero.