@alfredmouelle/create-stack 0.1.0 → 0.1.2

package/_stack/apps/tanstack-base/.vscode/settings.json

@@ -0,0 +1,35 @@
+{
+  "files.watcherExclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "search.exclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "files.readonlyInclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[css]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "editor.codeActionsOnSave": {
+    "source.organizeImports.biome": "explicit"
+  }
+}

package/_stack/apps/tanstack-base/.zed/settings.json

@@ -0,0 +1,45 @@
+{
+  "lsp": {
+    "biome": {
+      "settings": {
+        "require_config_file": true,
+        "config_path": "biome.jsonc"
+      }
+    }
+  },
+
+  "languages": {
+    "Markdown": {
+      "formatter": { "language_server": { "name": "biome" } }
+    },
+    "JSONC": {
+      "formatter": { "language_server": { "name": "biome" } }
+    },
+    "JSON": {
+      "formatter": { "language_server": { "name": "biome" } }
+    },
+    "HTML": { "formatter": { "language_server": { "name": "biome" } } },
+    "CSS": { "formatter": { "language_server": { "name": "biome" } } },
+    "JavaScript": {
+      "formatter": { "language_server": { "name": "biome" } },
+      "code_actions_on_format": {
+        "source.fixAll.biome": true,
+        "source.organizeImports.biome": true
+      }
+    },
+    "TypeScript": {
+      "formatter": { "language_server": { "name": "biome" } },
+      "code_actions_on_format": {
+        "source.fixAll.biome": true,
+        "source.organizeImports.biome": true
+      }
+    },
+    "TSX": {
+      "formatter": { "language_server": { "name": "biome" } },
+      "code_actions_on_format": {
+        "source.fixAll.biome": true,
+        "source.organizeImports.biome": true
+      }
+    }
+  }
+}

package/_stack/apps/tanstack-base/src/components/form/text-field.tsx

@@ -14,7 +14,7 @@ interface TextFieldProps extends NativeInputProps {
   field: AnyFieldApi
   label: string
   description?: string
-  /** Optional leading adornment (e.g. a lucide icon). */
+  /** Leading adornment (e.g. lucide icon). */
   icon?: ReactNode
 }
 

package/_stack/apps/tanstack-base/src/components/ui/spinner.tsx

@@ -2,7 +2,7 @@ import { Loader2 } from 'lucide-react'
 import type { ComponentProps } from 'react'
 import { cn } from '~/lib/utils'
 
-/** Loading indicator — the lucide `loader` icon, spinning. */
+/** Spinning lucide `loader` icon. */
 export function Spinner({ className, ...props }: ComponentProps<typeof Loader2>) {
   return <Loader2 aria-hidden="true" className={cn('size-4 animate-spin', className)} {...props} />
 }

package/_stack/apps/tanstack-base/src/emails/components/components.tsx

@@ -5,9 +5,9 @@ import { createEmailTheme, type EmailTheme, type EmailThemeOverride } from './th
 export interface EmailLayoutProps {
   preview: string
   children: React.ReactNode
-  /** Per-email theme override, merged onto the default theme. */
+  /** Per-email theme override, merged onto default. */
   theme?: EmailTheme | EmailThemeOverride
-  /** Footer year. Pass explicitly to keep rendered output deterministic. */
+  /** Footer year; pass explicitly for deterministic output. */
   year?: number
 }
 

package/_stack/apps/tanstack-base/src/emails/components/context.tsx

@@ -12,7 +12,7 @@ export function EmailThemeProvider({ theme, children }: EmailThemeProviderProps)
   return <EmailThemeContext.Provider value={theme}>{children}</EmailThemeContext.Provider>
 }
 
-/** Read the active email theme. Falls back to {@link defaultTheme}. */
+/** Active email theme; falls back to {@link defaultTheme}. */
 export function useEmailTheme(): EmailTheme {
   return useContext(EmailThemeContext)
 }

package/_stack/apps/tanstack-base/src/emails/components/theme.ts

@@ -1,13 +1,12 @@
 /**
- * The swappable design tokens for emails. Override any subset via
- * {@link createEmailTheme} and pass the result to `<EmailLayout theme={...}>`,
- * or wrap a tree in `<EmailThemeProvider>`.
+ * Swappable email design tokens. Override a subset via {@link createEmailTheme}
+ * + `<EmailLayout theme={...}>`, or wrap a tree in `<EmailThemeProvider>`.
  */
 export interface EmailTheme {
   brand: {
-    /** Shown in the header band and footer. */
+    /** Header band + footer. */
     name: string
-    /** Footer line (the year is prefixed automatically). */
+    /** Footer line (year prefixed automatically). */
     footer: string
   }
   fontFamily: string
@@ -21,7 +20,7 @@ export interface EmailTheme {
     border: string
     borderSubtle: string
     destructive: string
-    /** Text color on top of accent/destructive buttons. */
+    /** Text over accent/destructive buttons. */
     onAccent: string
   }
 }
@@ -52,7 +51,7 @@ export type EmailThemeOverride = {
   colors?: Partial<EmailTheme['colors']>
 }
 
-/** Deep-merge an override onto a base theme (defaults to {@link defaultTheme}). */
+/** Deep-merge override onto base (defaults to {@link defaultTheme}). */
 export function createEmailTheme(
   override: EmailThemeOverride = {},
   base: EmailTheme = defaultTheme,

package/_stack/apps/tanstack-base/src/env.ts

@@ -1,15 +1,11 @@
 import { createEnv } from '@t3-oss/env-core'
 import * as v from 'valibot'
 
-/** Makes a var required only in production (optional in dev/test). */
+/** Required 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.
- */
+/** Typed env; foundations/capabilities extend `server` + `runtimeEnv` as needed. */
 export const env = createEnv({
   shared: {
     NODE_ENV: v.optional(v.picklist(['development', 'test', 'production']), 'development'),

package/_stack/apps/tanstack-base/src/lib/date.ts

@@ -1,4 +1,4 @@
 import { format } from 'date-fns'
 
-/** Format a Date as an ISO date string (yyyy-MM-dd). */
+/** Format as ISO date (yyyy-MM-dd). */
 export const toISODate = (date: Date): string => format(date, 'yyyy-MM-dd')

package/_stack/apps/tanstack-base/src/routes/__root.tsx

@@ -8,7 +8,7 @@ import TanStackQueryDevtools from '~/trpc/devtools'
 
 import appCss from '../styles.css?url'
 
-// Runs before hydration to set the theme class and avoid a flash of wrong theme.
+// Pre-hydration: set theme class to avoid flash of wrong theme.
 const themeScript = `(function(){try{var t=localStorage.getItem('theme')||'system';var m=window.matchMedia('(prefers-color-scheme:dark)').matches;document.documentElement.classList.toggle('dark',t==='dark'||(t==='system'&&m));}catch(e){}})();`
 
 interface RouterContext {

package/_stack/apps/tanstack-base/src/routes/_authed.tsx

@@ -1,10 +1,7 @@
 import { createFileRoute, Outlet, redirect } from '@tanstack/react-router'
 import { getServerSession } from '~/server/better-auth/session'
 
-/**
- * Layout group guarding every route under it: redirects to sign-in when there's
- * no session, and exposes the session to child loaders via `beforeLoad`.
- */
+/** Guards child routes: redirects to sign-in when no session; exposes session via `beforeLoad`. */
 export const Route = createFileRoute('/_authed')({
   beforeLoad: async () => {
     const session = await getServerSession()

package/_stack/apps/tanstack-base/src/routes/api/auth/$.ts

@@ -1,4 +1,4 @@
-// Loads the TanStack Start augmentation that adds `server` to route options.
+// Loads the Start augmentation adding `server` to route options.
 
 import { createFileRoute } from '@tanstack/react-router'
 import type {} from '@tanstack/react-start'

package/_stack/apps/tanstack-base/src/routes/api.trpc.$.tsx

@@ -1,5 +1,4 @@
-// Loads the TanStack Start augmentation that adds `server` to route options
-// (so this server route typechecks even without other react-start imports).
+// Loads TanStack Start augmentation adding `server` to route options (typechecks without other react-start imports).
 
 import { createFileRoute } from '@tanstack/react-router'
 import type {} from '@tanstack/react-start'

package/_stack/apps/tanstack-base/src/server/better-auth/config.ts

@@ -43,7 +43,7 @@ export const auth = betterAuth({
   },
   socialProviders,
   user: {
-    // Extend the user with extra columns here (mirror them in auth.schema.ts):
+    // Add extra columns here (mirror in auth.schema.ts):
     // additionalFields: {
     //   role: { type: 'string', defaultValue: 'user', input: false },
     // },

package/_stack/apps/tanstack-base/src/server/better-auth/session.ts

@@ -2,8 +2,15 @@ import { createServerFn } from '@tanstack/react-start'
 import { getRequest } from '@tanstack/react-start/server'
 import { auth } from '.'
 
-/** Raw session lookup from the current request headers (server-side). */
-export const getSession = async () => auth.api.getSession({ headers: getRequest().headers })
-
-/** Server-function wrapper for route loaders / `beforeLoad`. */
-export const getServerSession = createServerFn({ method: 'GET' }).handler(() => getSession())
+/**
+ * Server-fn resolving the better-auth session from request headers; use in
+ * loaders / `beforeLoad`.
+ *
+ * `getRequest` is called INSIDE the handler on purpose: the Start plugin
+ * extracts handlers server-side and strips the import from the client bundle.
+ * Calling it at module scope would leak `@tanstack/react-start/server` into
+ * client code (routes import this transitively) and trip import-protection.
+ */
+export const getServerSession = createServerFn({ method: 'GET' }).handler(() =>
+  auth.api.getSession({ headers: getRequest().headers }),
+)

package/_stack/apps/tanstack-base/src/server/db/schemas/index.ts

@@ -1,2 +1,2 @@
-// Barrel of every Drizzle schema. Add one `export *` line per `*.schema.ts`.
+// Drizzle schema barrel; one `export *` per `*.schema.ts`.
 export * from './auth.schema'

package/_stack/apps/tanstack-base/src/server/db/seed.ts

@@ -3,11 +3,11 @@ import { config } from 'dotenv'
 
 config({ path: ['.env.local', '.env'] })
 
-// Deterministic data across runs.
+// Deterministic across runs.
 faker.seed(42)
 
 async function main() {
-  // Import the db client and seed your tables here (idempotent), using faker:
+  // Seed your tables here (idempotent) via faker:
   //   const { db } = await import('~/server/db')
   //   await db.insert(user).values({
   //     id: faker.string.uuid(),

package/_stack/apps/tanstack-base/src/server/email/adapters/resend/index.ts

@@ -4,7 +4,7 @@ import { formatAddress } from '../../core/address'
 import { type MailerAdapter, MailerError, type RenderedMessage } from '../../core/port'
 import { ResendConfigSchema } from './config'
 
-/** Minimal structural view of the Resend client we depend on (eases testing). */
+/** Minimal structural view of the Resend client (eases testing). */
 export interface ResendClient {
   emails: {
     send(payload: ResendSendPayload): Promise<{
@@ -30,7 +30,7 @@ interface ResendSendPayload {
 
 export interface ResendAdapterOptions {
   apiKey: string
-  /** Inject a custom/mock client. Defaults to a real `Resend` instance. */
+  /** Custom/mock client; defaults to a real `Resend`. */
   client?: ResendClient
 }
 
@@ -39,7 +39,7 @@ function toAttachmentContent(content: Uint8Array | string): Buffer | string {
 }
 
 export function resendAdapter(options: ResendAdapterOptions): MailerAdapter {
-  // Validate config early so a missing key fails at construction, not at send().
+  // Validate early so a missing key fails at construction, not send().
   const config = v.parse(ResendConfigSchema, { apiKey: options.apiKey })
   const client: ResendClient =
     options.client ?? (new Resend(config.apiKey) as unknown as ResendClient)

package/_stack/apps/tanstack-base/src/server/email/core/address.ts

@@ -2,7 +2,7 @@ import type { MailAddress, MailRecipient } from './port'
 
 const ADDRESS_RE = /^\s*(.*?)\s*<([^>]+)>\s*$/
 
-/** Coerce a recipient into a structured {@link MailAddress}. */
+/** Coerce a recipient to a structured {@link MailAddress}. */
 export function normalizeAddress(input: MailRecipient): MailAddress {
   if (typeof input !== 'string') return input
   const match = input.match(ADDRESS_RE)
@@ -10,12 +10,12 @@ export function normalizeAddress(input: MailRecipient): MailAddress {
   return { email: input.trim() }
 }
 
-/** Coerce a single recipient or list into a normalized array. */
+/** Coerce a recipient or list to a normalized array. */
 export function normalizeRecipients(input: MailRecipient | MailRecipient[]): MailAddress[] {
   return (Array.isArray(input) ? input : [input]).map(normalizeAddress)
 }
 
-/** Render an address back to an RFC-style string (`Name <email>`). */
+/** Render an address to RFC-style `Name <email>`. */
 export function formatAddress(address: MailAddress): string {
   return address.name ? `${address.name} <${address.email}>` : address.email
 }

package/_stack/apps/tanstack-base/src/server/email/core/port.ts

@@ -1,41 +1,37 @@
 import type { ReactElement } from 'react'
 
-/** A structured email address. */
+/** Structured email address. */
 export interface MailAddress {
   email: string
   name?: string
 }
 
-/**
- * A recipient, either as a plain string (`"hi@acme.com"` or
- * `"Acme <hi@acme.com>"`) or a structured {@link MailAddress}.
- */
+/** Recipient: string (`"hi@acme.com"` / `"Acme <hi@acme.com>"`) or {@link MailAddress}. */
 export type MailRecipient = string | MailAddress
 
 export interface MailAttachment {
   filename: string
-  /** Raw bytes or a base64 string. */
+  /** Raw bytes or base64 string. */
   content: Uint8Array | string
   contentType?: string
 }
 
 /**
- * A message as authored by application code. We never send raw HTML strings:
- * the body is always a React Email component, rendered to HTML + plain text by
- * the mailer before it reaches the adapter.
+ * Message as authored by app code. Never raw HTML: the body is always a React
+ * Email component, rendered to HTML + text by the mailer before the adapter.
  */
 export interface MailMessage {
   to: MailRecipient | MailRecipient[]
   subject: string
-  /** A React Email component. Rendered to HTML and plain text automatically. */
+  /** React Email component; rendered to HTML + text automatically. */
   react: ReactElement
-  /** Overrides the default `from` configured on the mailer. */
+  /** Overrides the mailer's default `from`. */
   from?: MailRecipient
   replyTo?: MailRecipient
   cc?: MailRecipient | MailRecipient[]
   bcc?: MailRecipient | MailRecipient[]
   headers?: Record<string, string>
-  /** Provider-agnostic key/value tags for analytics & filtering. */
+  /** Provider-agnostic tags for analytics & filtering. */
   tags?: Record<string, string>
   attachments?: MailAttachment[]
 }
@@ -45,18 +41,12 @@ export interface SentMail {
   id: string
 }
 
-/**
- * The port the application depends on. Swapping providers means swapping the
- * adapter passed to {@link createMailer}; this interface never changes.
- */
+/** The port the app depends on; swap providers via {@link createMailer}'s adapter — this never changes. */
 export interface Mailer {
   send(message: MailMessage): Promise<SentMail>
 }
 
-/**
- * The message shape an adapter receives: addresses are normalized and the body
- * is already rendered to `html` + `text`. Adapters do no rendering.
- */
+/** Shape an adapter receives: normalized addresses, body pre-rendered to `html` + `text`. Adapters don't render. */
 export interface RenderedMessage {
   to: MailAddress[]
   from: MailAddress
@@ -71,13 +61,13 @@ export interface RenderedMessage {
   attachments?: MailAttachment[]
 }
 
-/** The contract each provider implements. Kept intentionally tiny. */
+/** Contract each provider implements; intentionally tiny. */
 export interface MailerAdapter {
   readonly name: string
   send(message: RenderedMessage): Promise<SentMail>
 }
 
-/** Normalized error thrown by adapters so callers never catch provider types. */
+/** Normalized adapter error so callers never catch provider types. */
 export class MailerError extends Error {
   readonly adapter: string
 

package/_stack/apps/tanstack-base/src/server/email/core/render.ts

@@ -6,7 +6,7 @@ export interface RenderedBody {
   text: string
 }
 
-/** A function that turns a React Email component into HTML + plain text. */
+/** Turns a React Email component into HTML + plain text. */
 export type EmailRenderer = (react: ReactElement) => Promise<RenderedBody>
 
 /** Default renderer backed by `@react-email/render`. */

package/_stack/apps/tanstack-base/src/server/email/factory.ts

@@ -3,21 +3,20 @@ import type { Mailer, MailerAdapter, MailRecipient, RenderedMessage } from './co
 import { type EmailRenderer, renderEmail } from './core/render'
 
 export interface CreateMailerOptions {
-  /** The provider implementation (Resend, Brevo, …). */
+  /** Provider impl (Resend, Brevo, …). */
   adapter: MailerAdapter
-  /** Default sender used when a message omits `from`. */
+  /** Default sender when a message omits `from`. */
   from: MailRecipient
-  /** Override the React Email renderer (mostly for tests). */
+  /** Override the renderer (mostly for tests). */
   render?: EmailRenderer
 }
 
 /**
- * Build a {@link Mailer}. This is the composition root: pick the adapter here,
- * the rest of the app depends only on the `Mailer` port.
+ * Build a {@link Mailer}. Composition root: pick the adapter here; the rest of
+ * the app depends only on the `Mailer` port.
  *
- * The mailer renders the React body to HTML + plain text, normalizes every
- * address, applies the default sender, then hands a {@link RenderedMessage} to
- * the adapter.
+ * Renders the React body to HTML + text, normalizes addresses, applies the
+ * default sender, then hands a {@link RenderedMessage} to the adapter.
  */
 export function createMailer(options: CreateMailerOptions): Mailer {
   const defaultFrom = normalizeAddress(options.from)

package/_stack/apps/tanstack-base/src/server/email/index.ts

@@ -11,7 +11,7 @@ function required(value: string | undefined, name: string): string {
   return value
 }
 
-// Lazy so the app boots without RESEND_API_KEY; the adapter is built on first send.
+// Lazy so the app boots without RESEND_API_KEY; adapter built on first send.
 let mailer: Mailer | null = null
 function getMailer(): Mailer {
   if (!mailer) {

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

@@ -28,7 +28,7 @@ interface BrevoSendResponse {
   messageIds?: string[]
 }
 
-/** Minimal structural view of the Brevo client we depend on (eases testing). */
+/** Structural view of the Brevo client (eases testing). */
 export interface BrevoClientLike {
   transactionalEmails: {
     sendTransacEmail(request: BrevoSendRequest): Promise<BrevoSendResponse>
@@ -37,7 +37,7 @@ export interface BrevoClientLike {
 
 export interface BrevoAdapterOptions {
   apiKey: string
-  /** Inject a custom/mock client. Defaults to a real `BrevoClient`. */
+  /** Inject custom/mock client. Defaults to real `BrevoClient`. */
   client?: BrevoClientLike
 }
 
@@ -50,7 +50,7 @@ function toBase64(content: Uint8Array | string): string {
 }
 
 export function brevoAdapter(options: BrevoAdapterOptions): MailerAdapter {
-  // Validate config early so a missing key fails at construction, not at send().
+  // Validate early: missing key fails at construction, not send().
   const config = v.parse(BrevoConfigSchema, { apiKey: options.apiKey })
   const client: BrevoClientLike =
     options.client ?? (new BrevoClient({ apiKey: config.apiKey }) as unknown as BrevoClientLike)

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

@@ -4,7 +4,7 @@ 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). */
+/** Structural view of the Resend client (eases testing). */
 export interface ResendClient {
   emails: {
     send(payload: ResendSendPayload): Promise<{
@@ -30,7 +30,7 @@ interface ResendSendPayload {
 
 export interface ResendAdapterOptions {
   apiKey: string
-  /** Inject a custom/mock client. Defaults to a real `Resend` instance. */
+  /** Inject custom/mock client. Defaults to real `Resend`. */
   client?: ResendClient
 }
 
@@ -39,7 +39,7 @@ function toAttachmentContent(content: Uint8Array | string): Buffer | string {
 }
 
 export function resendAdapter(options: ResendAdapterOptions): MailerAdapter {
-  // Validate config early so a missing key fails at construction, not at send().
+  // Validate early: missing key fails at construction, not send().
   const config = v.parse(ResendConfigSchema, { apiKey: options.apiKey })
   const client: ResendClient =
     options.client ?? (new Resend(config.apiKey) as unknown as ResendClient)

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

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

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

@@ -5,7 +5,7 @@ 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). */
+/** Structural view of the SESv2 client (eases testing). */
 export interface SesClientLike {
   send(command: { input: SesSendEmailInput }): Promise<{ MessageId?: string }>
 }
@@ -26,12 +26,12 @@ interface SesSendEmailInput {
 }
 
 export interface SesAdapterOptions {
-  /** AWS region. Falls back to the SDK's resolution (e.g. `AWS_REGION`). */
+  /** AWS region. Falls back to SDK resolution (e.g. `AWS_REGION`). */
   region?: string
   accessKeyId?: string
   secretAccessKey?: string
   configurationSetName?: string
-  /** Inject a custom/mock client. Defaults to a real `SESv2Client`. */
+  /** Inject custom/mock client. Defaults to real `SESv2Client`. */
   client?: SesClientLike
 }
 
@@ -56,8 +56,7 @@ export function sesAdapter(options: SesAdapterOptions = {}): MailerAdapter {
   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.
+      // SES Simple content can't carry attachments (needs raw MIME, not built here). Fail loudly.
       if (message.attachments?.length) {
         throw new MailerError('SES adapter does not support attachments (requires raw MIME)', {
           adapter: 'ses',