@alfredmouelle/create-stack 0.1.0

package/_stack/packages/mailer/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@alfredmouelle/mailer",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aws-sdk/client-sesv2": "^3.1073.0",
+    "@getbrevo/brevo": "^5.0.4",
+    "resend": "^6.14.0",
+    "valibot": "^1.4.1"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "react-email": "^6.6.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.1",
+    "@types/react-dom": "^19.0.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-email": "^6.6.3",
+    "tsdown": "^0.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}

package/_stack/packages/mailer/src/adapters/brevo/config.ts

@@ -0,0 +1,7 @@
+import * as v from 'valibot'
+
+export const BrevoConfigSchema = v.object({
+  apiKey: v.pipe(v.string(), v.minLength(1, 'BREVO_API_KEY is required')),
+})
+
+export type BrevoConfig = v.InferOutput<typeof BrevoConfigSchema>

package/_stack/packages/mailer/src/adapters/brevo/index.ts

@@ -0,0 +1,90 @@
+import { BrevoClient } from '@getbrevo/brevo'
+import * as v from 'valibot'
+import type { MailAddress } from '../../core/port.js'
+import { type MailerAdapter, MailerError, type RenderedMessage } from '../../core/port.js'
+import { BrevoConfigSchema } from './config.js'
+
+interface BrevoContact {
+  email: string
+  name?: string
+}
+
+interface BrevoSendRequest {
+  sender: BrevoContact
+  to: BrevoContact[]
+  subject: string
+  htmlContent: string
+  textContent: string
+  replyTo?: BrevoContact
+  cc?: BrevoContact[]
+  bcc?: BrevoContact[]
+  headers?: Record<string, unknown>
+  tags?: string[]
+  attachment?: { name: string; content: string }[]
+}
+
+interface BrevoSendResponse {
+  messageId?: string
+  messageIds?: string[]
+}
+
+/** Minimal structural view of the Brevo client we depend on (eases testing). */
+export interface BrevoClientLike {
+  transactionalEmails: {
+    sendTransacEmail(request: BrevoSendRequest): Promise<BrevoSendResponse>
+  }
+}
+
+export interface BrevoAdapterOptions {
+  apiKey: string
+  /** Inject a custom/mock client. Defaults to a real `BrevoClient`. */
+  client?: BrevoClientLike
+}
+
+function toContact(address: MailAddress): BrevoContact {
+  return { email: address.email, name: address.name }
+}
+
+function toBase64(content: Uint8Array | string): string {
+  return typeof content === 'string' ? content : Buffer.from(content).toString('base64')
+}
+
+export function brevoAdapter(options: BrevoAdapterOptions): MailerAdapter {
+  // Validate config early so a missing key fails at construction, not at send().
+  const config = v.parse(BrevoConfigSchema, { apiKey: options.apiKey })
+  const client: BrevoClientLike =
+    options.client ?? (new BrevoClient({ apiKey: config.apiKey }) as unknown as BrevoClientLike)
+
+  return {
+    name: 'brevo',
+    async send(message: RenderedMessage) {
+      try {
+        const response = await client.transactionalEmails.sendTransacEmail({
+          sender: toContact(message.from),
+          to: message.to.map(toContact),
+          subject: message.subject,
+          htmlContent: message.html,
+          textContent: message.text,
+          replyTo: message.replyTo ? toContact(message.replyTo) : undefined,
+          cc: message.cc?.map(toContact),
+          bcc: message.bcc?.map(toContact),
+          headers: message.headers,
+          tags: message.tags
+            ? Object.entries(message.tags).map(([k, val]) => `${k}:${val}`)
+            : undefined,
+          attachment: message.attachments?.map((a) => ({
+            name: a.filename,
+            content: toBase64(a.content),
+          })),
+        })
+
+        const id = response.messageId ?? response.messageIds?.[0]
+        if (!id) throw new MailerError('Brevo returned no messageId', { adapter: 'brevo' })
+        return { id }
+      } catch (cause) {
+        if (cause instanceof MailerError) throw cause
+        throw new MailerError('Brevo request failed', { adapter: 'brevo', cause })
+      }
+    },
+  }
+}

package/_stack/packages/mailer/src/adapters/resend/config.ts

@@ -0,0 +1,7 @@
+import * as v from 'valibot'
+
+export const ResendConfigSchema = v.object({
+  apiKey: v.pipe(v.string(), v.minLength(1, 'RESEND_API_KEY is required')),
+})
+
+export type ResendConfig = v.InferOutput<typeof ResendConfigSchema>

package/_stack/packages/mailer/src/adapters/resend/index.ts

@@ -0,0 +1,75 @@
+import { Resend } from 'resend'
+import * as v from 'valibot'
+import { formatAddress } from '../../core/address.js'
+import { type MailerAdapter, MailerError, type RenderedMessage } from '../../core/port.js'
+import { ResendConfigSchema } from './config.js'
+
+/** Minimal structural view of the Resend client we depend on (eases testing). */
+export interface ResendClient {
+  emails: {
+    send(payload: ResendSendPayload): Promise<{
+      data: { id: string } | null
+      error: { message: string; name?: string } | null
+    }>
+  }
+}
+
+interface ResendSendPayload {
+  from: string
+  to: string[]
+  subject: string
+  html: string
+  text: string
+  replyTo?: string
+  cc?: string[]
+  bcc?: string[]
+  headers?: Record<string, string>
+  tags?: { name: string; value: string }[]
+  attachments?: { filename: string; content: Buffer | string; contentType?: string }[]
+}
+
+export interface ResendAdapterOptions {
+  apiKey: string
+  /** Inject a custom/mock client. Defaults to a real `Resend` instance. */
+  client?: ResendClient
+}
+
+function toAttachmentContent(content: Uint8Array | string): Buffer | string {
+  return typeof content === 'string' ? content : Buffer.from(content)
+}
+
+export function resendAdapter(options: ResendAdapterOptions): MailerAdapter {
+  // Validate config early so a missing key fails at construction, not at send().
+  const config = v.parse(ResendConfigSchema, { apiKey: options.apiKey })
+  const client: ResendClient =
+    options.client ?? (new Resend(config.apiKey) as unknown as ResendClient)
+
+  return {
+    name: 'resend',
+    async send(message: RenderedMessage) {
+      const { data, error } = await client.emails.send({
+        from: formatAddress(message.from),
+        to: message.to.map(formatAddress),
+        subject: message.subject,
+        html: message.html,
+        text: message.text,
+        replyTo: message.replyTo ? formatAddress(message.replyTo) : undefined,
+        cc: message.cc?.map(formatAddress),
+        bcc: message.bcc?.map(formatAddress),
+        headers: message.headers,
+        tags: message.tags
+          ? Object.entries(message.tags).map(([name, value]) => ({ name, value }))
+          : undefined,
+        attachments: message.attachments?.map((a) => ({
+          filename: a.filename,
+          content: toAttachmentContent(a.content),
+          contentType: a.contentType,
+        })),
+      })
+
+      if (error) throw new MailerError(error.message, { adapter: 'resend', cause: error })
+      if (!data) throw new MailerError('Resend returned no data', { adapter: 'resend' })
+      return { id: data.id }
+    },
+  }
+}

package/_stack/packages/mailer/src/adapters/ses/config.ts

@@ -0,0 +1,13 @@
+import * as v from 'valibot'
+
+export const SesConfigSchema = v.object({
+  /** AWS region. Falls back to the SDK's resolution (e.g. `AWS_REGION`). */
+  region: v.optional(v.string()),
+  /** Static credentials. Omit to let the SDK resolve them (env, profile, IAM). */
+  accessKeyId: v.optional(v.string()),
+  secretAccessKey: v.optional(v.string()),
+  /** SES configuration set to attach (event publishing, dedicated IPs, …). */
+  configurationSetName: v.optional(v.string()),
+})
+
+export type SesConfig = v.InferOutput<typeof SesConfigSchema>

package/_stack/packages/mailer/src/adapters/ses/index.ts

@@ -0,0 +1,103 @@
+// biome-ignore-all lint/style/useNamingConvention: SESv2's API uses PascalCase keys
+import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2'
+import * as v from 'valibot'
+import { formatAddress } from '../../core/address.js'
+import { type MailerAdapter, MailerError, type RenderedMessage } from '../../core/port.js'
+import { SesConfigSchema } from './config.js'
+
+/** Minimal structural view of the SESv2 client we depend on (eases testing). */
+export interface SesClientLike {
+  send(command: { input: SesSendEmailInput }): Promise<{ MessageId?: string }>
+}
+
+interface SesSendEmailInput {
+  FromEmailAddress: string
+  Destination: { ToAddresses: string[]; CcAddresses?: string[]; BccAddresses?: string[] }
+  Content: {
+    Simple: {
+      Subject: { Data: string }
+      Body: { Html: { Data: string }; Text: { Data: string } }
+      Headers?: { Name: string; Value: string }[]
+    }
+  }
+  ReplyToAddresses?: string[]
+  EmailTags?: { Name: string; Value: string }[]
+  ConfigurationSetName?: string
+}
+
+export interface SesAdapterOptions {
+  /** AWS region. Falls back to the SDK's resolution (e.g. `AWS_REGION`). */
+  region?: string
+  accessKeyId?: string
+  secretAccessKey?: string
+  configurationSetName?: string
+  /** Inject a custom/mock client. Defaults to a real `SESv2Client`. */
+  client?: SesClientLike
+}
+
+export function sesAdapter(options: SesAdapterOptions = {}): MailerAdapter {
+  const config = v.parse(SesConfigSchema, {
+    region: options.region,
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    configurationSetName: options.configurationSetName,
+  })
+
+  const client: SesClientLike =
+    options.client ??
+    (new SESv2Client({
+      region: config.region,
+      credentials:
+        config.accessKeyId && config.secretAccessKey
+          ? { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey }
+          : undefined,
+    }) as unknown as SesClientLike)
+
+  return {
+    name: 'ses',
+    async send(message: RenderedMessage) {
+      // SES's Simple content can't carry attachments — that needs a raw MIME
+      // message, which this adapter intentionally doesn't build. Fail loudly.
+      if (message.attachments?.length) {
+        throw new MailerError('SES adapter does not support attachments (requires raw MIME)', {
+          adapter: 'ses',
+        })
+      }
+
+      const input: SesSendEmailInput = {
+        FromEmailAddress: formatAddress(message.from),
+        Destination: {
+          ToAddresses: message.to.map(formatAddress),
+          CcAddresses: message.cc?.map(formatAddress),
+          BccAddresses: message.bcc?.map(formatAddress),
+        },
+        Content: {
+          Simple: {
+            Subject: { Data: message.subject },
+            Body: { Html: { Data: message.html }, Text: { Data: message.text } },
+            Headers: message.headers
+              ? Object.entries(message.headers).map(([Name, Value]) => ({ Name, Value }))
+              : undefined,
+          },
+        },
+        ReplyToAddresses: message.replyTo ? [formatAddress(message.replyTo)] : undefined,
+        EmailTags: message.tags
+          ? Object.entries(message.tags).map(([Name, Value]) => ({ Name, Value }))
+          : undefined,
+        ConfigurationSetName: config.configurationSetName,
+      }
+
+      try {
+        const result = await client.send(
+          new SendEmailCommand(input) as { input: SesSendEmailInput },
+        )
+        if (!result.MessageId)
+          throw new MailerError('SES returned no MessageId', { adapter: 'ses' })
+        return { id: result.MessageId }
+      } catch (cause) {
+        if (cause instanceof MailerError) throw cause
+        throw new MailerError('SES request failed', { adapter: 'ses', cause })
+      }
+    },
+  }
+}

package/_stack/packages/storage/capability.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "storage",
+  "description": "Object storage behind a swappable port: put/get/delete/exists plus signed URLs. Adapters for S3, Cloudflare R2, Google Cloud Storage and the local filesystem.",
+  "port": "src/core/port.ts",
+  "factory": "src/index.ts",
+  "defaultAdapter": "s3",
+  "adapters": {
+    "s3": {
+      "deps": ["@aws-sdk/client-s3", "@aws-sdk/s3-request-presigner"],
+      "env": ["S3_BUCKET", "S3_REGION", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"],
+      "files": ["src/adapters/s3"]
+    },
+    "r2": {
+      "deps": ["@aws-sdk/client-s3", "@aws-sdk/s3-request-presigner"],
+      "env": ["R2_BUCKET", "R2_ACCOUNT_ID", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY"],
+      "files": ["src/adapters/r2", "src/adapters/s3"]
+    },
+    "gcs": {
+      "deps": ["@google-cloud/storage"],
+      "env": ["GCS_BUCKET", "GOOGLE_CLOUD_PROJECT"],
+      "files": ["src/adapters/gcs"]
+    },
+    "local": {
+      "deps": [],
+      "env": ["STORAGE_LOCAL_DIR"],
+      "files": ["src/adapters/local"]
+    }
+  },
+  "sharedDeps": ["valibot"],
+  "sharedFiles": ["src/core", "src/index.ts"]
+}

package/_stack/patterns/README.md

@@ -0,0 +1,58 @@
+# Patterns
+
+Foundational, framework-coupled **patterns** the `bootstrap` skill vendors into a
+freshly scaffolded app — the counterpart to `packages/` (swappable capabilities).
+
+A *capability* is a provider behind a port (mailer, storage, …), swappable by
+changing one line. A *pattern* is a foundation you don't swap but always set up
+the same way: tRPC wiring, the better-auth instance, the Drizzle client. They are
+**framework-coupled** (currently `tanstack-start`, mirrored from the reference
+base apps) and depend on each other.
+
+**The code lives in the base apps, not here.** `patterns/` is a pure *manifest
+layer*: each `pattern.json` describes a foundation (how to detect it, its deps,
+env, framework, dependencies) and lists the files that make it up — by pointing
+**into the base apps** (`apps/tanstack-base`, `apps/next-base`), the single source
+of truth. No code is duplicated.
+
+Each pattern is `<name>/pattern.json` (see `../pattern.schema.json`).
+`_baseline/` is special: real always-applied config files (Biome, tsconfig, env
+skeleton, the `# Author` README footer) that a standalone fork needs but the base
+apps don't carry on their own (they inherit the monorepo's Biome).
+
+## How the skills use these
+
+The manifests drive two flows:
+
+- **bootstrap — create mode** (empty folder): fork a base app, then *strip* every
+  foundation/capability the user didn't pick, using each manifest's `files`/`deps`/
+  `env` to know its exact footprint.
+- **bootstrap — existing project / add-capability**: match each manifest's `detect`
+  against the project → the opt-in set, then *vendor* the listed files (copied from
+  the base apps) + deps + env, wire `integratesWith` when both sides are opt-in, and
+  pull required `capabilities`. A pattern not referenced is never pulled.
+
+## Available patterns
+
+- **drizzle** — Drizzle ORM + drizzle-kit (Postgres). Client, schema barrel,
+  cursor pagination, seed harness.
+- **better-auth** — better-auth v1 with the Drizzle adapter. Email+password,
+  verification, optional Google OAuth, rate limiting, auth tables, client +
+  session helpers, route guard. `dependsOn` drizzle; needs the mailer + email-kit
+  capabilities.
+- **trpc** — tRPC v11 + TanStack React Query. Context, procedure tiers, error
+  formatter, client + SSR caller, fetch handler. `dependsOn` drizzle,
+  `integratesWith` better-auth.
+- **data-table** — headless tables with TanStack Table (table + skeleton
+  primitives, DataTable, InfiniteDataTable, SortableHeader). `framework: agnostic`
+  — works in both Next and TanStack Start.
+
+Next.js variants (App Router) of the framework-coupled patterns:
+
+- **better-auth-next** — better-auth with `next/headers` session, `toNextJsHandler`
+  catch-all, server-component guards (`requireAuth`).
+- **trpc-next** — tRPC with the classic `api.x.useQuery` hooks (createTRPCReact) +
+  RSC hydration. `integratesWith` better-auth-next.
+
+bootstrap picks the variant matching the project's framework: `trpc`/`better-auth`
+for TanStack Start, `trpc-next`/`better-auth-next` for Next.

package/_stack/patterns/_baseline/README-author.md

@@ -0,0 +1,10 @@
+# Author
+
+Alfred MOUELLE | FullStack Developer
+
+[![ComeUp](https://img.shields.io/static/v1?style=for-the-badge&label=&message=ComeUp&color=yellow)](https://comeup.com/@alfredmouelle)
+[![GitHub](https://img.shields.io/badge/GitHub-100000?style=for-the-badge&logo=github&logoColor=white)](https://github.com/alfredmouelle)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/alfredmouelle)
+[![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://twitter.com/kali47_)
+[![Gmail](https://img.shields.io/badge/Gmail-D14836?style=for-the-badge&logo=gmail&logoColor=white)](mailto:alfredmouelle@gmail.com)
+[![Portfolio](https://img.shields.io/static/v1?style=for-the-badge&label=&message=Portfolio&color=blue)](https://alfredmouelle.com)

package/_stack/patterns/_baseline/biome.jsonc

@@ -0,0 +1,119 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "root": true,
+  "files": {
+    "includes": [
+      "**",
+      "!public",
+      "!**/dist",
+      "!**/.next",
+      "!**/.output",
+      "!**/.nitro",
+      "!**/routeTree.gen.ts",
+      "!**/components/ui"
+    ]
+  },
+  "vcs": {
+    "enabled": true,
+    "useIgnoreFile": true,
+    "clientKind": "git"
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on",
+        "useSortedAttributes": "on"
+      }
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentWidth": 2,
+    "indentStyle": "space",
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "domains": {
+      "react": "recommended",
+      "test": "recommended"
+    },
+    "rules": {
+      "suspicious": {
+        "noArrayIndexKey": "off",
+        "noConsole": {
+          "level": "warn",
+          "options": { "allow": ["warn", "error"] }
+        }
+      },
+      "complexity": {
+        "noExcessiveCognitiveComplexity": "warn"
+      },
+      "correctness": {
+        "noUndeclaredDependencies": "error"
+      },
+      "style": {
+        "noInferrableTypes": "error",
+        "useNamingConvention": {
+          "level": "warn",
+          "options": {
+            "strictCase": false,
+            "conventions": [{ "selector": { "kind": "objectLiteralProperty" }, "match": ".*" }]
+          }
+        },
+        "useConsistentArrayType": {
+          "level": "error",
+          "options": { "syntax": "shorthand" }
+        }
+      },
+      "a11y": {
+        "noStaticElementInteractions": "off",
+        "useKeyWithClickEvents": "off"
+      },
+      "nursery": {
+        "useSortedClasses": {
+          "level": "warn",
+          "fix": "safe",
+          "options": {
+            "functions": ["clsx", "cva", "cn"]
+          }
+        }
+      }
+    }
+  },
+  "html": {
+    "formatter": {
+      "enabled": true
+    }
+  },
+  "javascript": {
+    "assist": {
+      "enabled": true
+    },
+    "formatter": {
+      "enabled": true,
+      "quoteStyle": "single",
+      "semicolons": "asNeeded",
+      "trailingCommas": "all"
+    },
+    "linter": {
+      "enabled": true
+    }
+  },
+  "css": {
+    "assist": {
+      "enabled": true
+    },
+    "formatter": {
+      "enabled": true
+    },
+    "linter": {
+      "enabled": true
+    },
+    "parser": {
+      "cssModules": true,
+      "tailwindDirectives": true
+    }
+  }
+}

package/_stack/patterns/_baseline/env.ts

@@ -0,0 +1,31 @@
+import { createEnv } from '@t3-oss/env-core';
+import * as v from 'valibot';
+
+/** Makes a var required only in production (optional in dev/test). */
+export const requiredInProduction = <T extends v.GenericSchema>(schema: T) =>
+  process.env.NODE_ENV === 'production' ? schema : v.optional(schema);
+
+/**
+ * Typed environment. Start minimal — patterns (drizzle, better-auth, …) and
+ * capabilities (add-capability) extend the `server` block and `runtimeEnv` with
+ * the keys they need.
+ */
+export const env = createEnv({
+  shared: {
+    NODE_ENV: v.optional(
+      v.picklist(['development', 'test', 'production']),
+      'development',
+    ),
+  },
+
+  server: {
+    // Extended by patterns/capabilities (DATABASE_URL, BETTER_AUTH_SECRET, …).
+  },
+
+  runtimeEnv: {
+    NODE_ENV: process.env.NODE_ENV,
+  },
+
+  skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+  emptyStringAsUndefined: true,
+});

package/_stack/patterns/_baseline/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "include": ["**/*.ts", "**/*.tsx"],
+  "compilerOptions": {
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "paths": {
+      "~/*": ["./src/*"]
+    },
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    /* Linting */
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  }
+}