devstack 0.1.0

package/vendor/skills/skills/tanstack-start-best-practices/rules/deploy-adapters.md

@@ -0,0 +1,197 @@
+# deploy-adapters: Choose Appropriate Deployment Adapter
+
+## Priority: LOW
+
+## Explanation
+
+TanStack Start uses deployment adapters to target different hosting platforms. Each adapter optimizes the build output for its platform's runtime, edge functions, and static hosting capabilities.
+
+## Bad Example
+
+```tsx
+// Not configuring adapter - using defaults may not match your host
+// app.config.ts
+export default defineConfig({
+  // No adapter specified
+  // May not work correctly on your deployment platform
+});
+
+// Or using wrong adapter for platform
+export default defineConfig({
+  server: {
+    preset: "node-server", // But deploying to Vercel Edge
+  },
+});
+```
+
+## Good Example: Vercel Deployment
+
+```tsx
+// app.config.ts
+import { defineConfig } from '@tanstack/react-start/config'
+
+export default defineConfig({
+  server: {
+    preset: 'vercel',
+    // Vercel-specific options
+  },
+})
+
+// vercel.json (optional, for customization)
+{
+  "framework": null,
+  "buildCommand": "npm run build",
+  "outputDirectory": ".output"
+}
+```
+
+## Good Example: Cloudflare Pages
+
+```tsx
+// app.config.ts
+import { defineConfig } from "@tanstack/react-start/config";
+
+export default defineConfig({
+  server: {
+    preset: "cloudflare-pages",
+  },
+});
+
+// wrangler.toml
+name = "my-tanstack-app";
+compatibility_date = "2024-01-01";
+pages_build_output_dir = ".output/public";
+
+// For Cloudflare Workers (full control)
+export default defineConfig({
+  server: {
+    preset: "cloudflare",
+  },
+});
+```
+
+## Good Example: Netlify
+
+```tsx
+// app.config.ts
+import { defineConfig } from "@tanstack/react-start/config";
+
+export default // netlify.toml
+defineConfig({
+  server: {
+    preset: "netlify",
+  },
+})[build];
+command = "npm run build";
+publish = ".output/public"[functions];
+directory = ".output/server";
+```
+
+## Good Example: Node.js Server
+
+```tsx
+// app.config.ts
+import { defineConfig } from '@tanstack/react-start/config'
+
+export default defineConfig({
+  server: {
+    preset: 'node-server',
+    // Optional: customize port
+  },
+})
+
+// Dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY .output .output
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+
+// Or run directly
+// node .output/server/index.mjs
+```
+
+## Good Example: Static Export (SPA)
+
+```tsx
+// app.config.ts
+import { defineConfig } from "@tanstack/react-start/config";
+
+export default defineConfig({
+  server: {
+    preset: "static",
+    prerender: {
+      routes: ["/"],
+      crawlLinks: true,
+    },
+  },
+});
+
+// Output: .output/public (static files only)
+// Host anywhere: GitHub Pages, S3, any static host
+```
+
+## Good Example: AWS Lambda
+
+```tsx
+// app.config.ts
+import { defineConfig } from '@tanstack/react-start/config'
+
+export default defineConfig({
+  server: {
+    preset: 'aws-lambda',
+  },
+})
+
+// Deploy with SST, Serverless Framework, or AWS CDK
+// serverless.yml example:
+service: my-tanstack-app
+provider:
+  name: aws
+  runtime: nodejs20.x
+functions:
+  app:
+    handler: .output/server/index.handler
+    events:
+      - http: ANY /
+      - http: ANY /{proxy+}
+```
+
+## Good Example: Bun Runtime
+
+```tsx
+// app.config.ts
+import { defineConfig } from "@tanstack/react-start/config";
+
+export default defineConfig({
+  server: {
+    preset: "bun",
+  },
+});
+
+// Run with: bun .output/server/index.mjs
+```
+
+## Adapter Comparison
+
+| Adapter            | Runtime   | Edge | Static | Best For               |
+| ------------------ | --------- | ---- | ------ | ---------------------- |
+| `vercel`           | Node/Edge | Yes  | Yes    | Vercel hosting         |
+| `cloudflare-pages` | Workers   | Yes  | Yes    | Cloudflare Pages       |
+| `cloudflare`       | Workers   | Yes  | No     | Cloudflare Workers     |
+| `netlify`          | Node      | Yes  | Yes    | Netlify hosting        |
+| `node-server`      | Node      | No   | No     | Docker, VPS, self-host |
+| `static`           | None      | No   | Yes    | Any static host        |
+| `aws-lambda`       | Node      | No   | No     | AWS serverless         |
+| `bun`              | Bun       | No   | No     | Bun runtime            |
+
+## Context
+
+- Adapters transform output for target platform
+- Edge adapters have API limitations (no file system, etc.)
+- Static preset requires all routes to be prerenderable
+- Test locally with `npm run build && npm run preview`
+- Check platform docs for runtime-specific constraints
+- Some platforms auto-detect TanStack Start (no adapter needed)

package/vendor/skills/skills/tanstack-start-best-practices/rules/env-functions.md

@@ -0,0 +1,207 @@
+# env-functions: Use Environment Functions for Configuration
+
+## Priority: MEDIUM
+
+## Explanation
+
+Environment functions provide type-safe access to environment variables on the server. They ensure secrets stay server-side, provide validation, and enable different configurations per environment (development, staging, production).
+
+## Bad Example
+
+```tsx
+// Accessing env vars directly - no validation, potential leaks
+export const getApiData = createServerFn().handler(async () => {
+  // No validation - may be undefined
+  const apiKey = process.env.API_KEY;
+
+  // Accidentally exposed in error messages
+  if (!apiKey) {
+    throw new Error(`Missing API_KEY: ${process.env}`);
+  }
+
+  return fetch(url, { headers: { Authorization: apiKey } });
+});
+
+// Or importing env in shared files
+// lib/config.ts
+export const config = {
+  apiKey: process.env.API_KEY, // Bundled into client!
+  dbUrl: process.env.DATABASE_URL,
+};
+```
+
+## Good Example: Validated Environment Configuration
+
+```tsx
+// lib/env.server.ts
+import { z } from "zod";
+
+const envSchema = z.object({
+  // Required
+  DATABASE_URL: z.string().url(),
+  SESSION_SECRET: z.string().min(32),
+
+  // API Keys
+  STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
+  STRIPE_WEBHOOK_SECRET: z.string().startsWith("whsec_"),
+
+  // Optional with defaults
+  NODE_ENV: z.enum(["development", "staging", "production"]).default("development"),
+  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+
+  // Optional
+  SENTRY_DSN: z.string().url().optional(),
+});
+
+export type Env = z.infer<typeof envSchema>;
+
+function validateEnv(): Env {
+  const parsed = envSchema.safeParse(process.env);
+
+  if (!parsed.success) {
+    console.error("Invalid environment variables:");
+    console.error(parsed.error.flatten().fieldErrors);
+    throw new Error("Invalid environment configuration");
+  }
+
+  return parsed.data;
+}
+
+// Validate once at startup
+export const env = validateEnv();
+
+// Usage in server functions
+export const getPaymentIntent = createServerFn({ method: "POST" }).handler(async () => {
+  const stripe = new Stripe(env.STRIPE_SECRET_KEY);
+  // Type-safe, validated access
+});
+```
+
+## Good Example: Public vs Private Config
+
+```tsx
+// lib/env.server.ts - Server only (secrets)
+export const serverEnv = {
+  databaseUrl: process.env.DATABASE_URL!,
+  sessionSecret: process.env.SESSION_SECRET!,
+  stripeSecretKey: process.env.STRIPE_SECRET_KEY!,
+};
+
+// lib/env.ts - Public config (safe for client)
+export const publicEnv = {
+  appUrl: process.env.VITE_APP_URL ?? "http://localhost:3000",
+  stripePublicKey: process.env.VITE_STRIPE_PUBLIC_KEY!,
+  sentryDsn: process.env.VITE_SENTRY_DSN,
+};
+
+// Vite exposes VITE_ prefixed vars to client
+// Non-prefixed vars are server-only
+```
+
+## Good Example: Environment-Specific Behavior
+
+```tsx
+// lib/env.server.ts
+export const env = validateEnv();
+
+export const isDevelopment = env.NODE_ENV === "development";
+export const isProduction = env.NODE_ENV === "production";
+export const isStaging = env.NODE_ENV === "staging";
+
+// lib/logger.server.ts
+import { env, isDevelopment } from "./env.server";
+
+export function log(level: string, message: string, data?: unknown) {
+  if (isDevelopment) {
+    console.log(`[${level}]`, message, data);
+    return;
+  }
+
+  // Production: send to logging service
+  if (env.SENTRY_DSN) {
+    // Send to Sentry
+  }
+}
+
+// Server function with environment checks
+export const debugInfo = createServerFn().handler(async () => {
+  if (isProduction) {
+    throw new Error("Debug endpoint not available in production");
+  }
+
+  return {
+    nodeVersion: process.version,
+    env: env.NODE_ENV,
+  };
+});
+```
+
+## Good Example: Feature Flags via Environment
+
+```tsx
+// lib/features.server.ts
+import { env } from "./env.server";
+
+export const features = {
+  newCheckout: env.FEATURE_NEW_CHECKOUT === "true",
+  betaDashboard: env.FEATURE_BETA_DASHBOARD === "true",
+  aiAssistant: env.FEATURE_AI_ASSISTANT === "true",
+};
+
+// Usage in server functions
+export const getCheckoutUrl = createServerFn().handler(async () => {
+  if (features.newCheckout) {
+    return "/checkout/v2";
+  }
+  return "/checkout";
+});
+
+// Usage in loaders
+export const Route = createFileRoute("/dashboard")({
+  loader: async () => {
+    return {
+      showBetaFeatures: features.betaDashboard,
+    };
+  },
+});
+```
+
+## Good Example: Type-Safe env.d.ts
+
+```tsx
+// env.d.ts - TypeScript declarations for env vars
+declare namespace NodeJS {
+  interface ProcessEnv {
+    // Required
+    DATABASE_URL: string;
+    SESSION_SECRET: string;
+
+    // Optional
+    NODE_ENV?: "development" | "staging" | "production";
+    SENTRY_DSN?: string;
+
+    // Vite public vars
+    VITE_APP_URL?: string;
+    VITE_STRIPE_PUBLIC_KEY: string;
+  }
+}
+```
+
+## Environment Variable Checklist
+
+| Variable                 | Prefix  | Accessible On   |
+| ------------------------ | ------- | --------------- |
+| `DATABASE_URL`           | None    | Server only     |
+| `SESSION_SECRET`         | None    | Server only     |
+| `STRIPE_SECRET_KEY`      | None    | Server only     |
+| `VITE_APP_URL`           | `VITE_` | Server + Client |
+| `VITE_STRIPE_PUBLIC_KEY` | `VITE_` | Server + Client |
+
+## Context
+
+- Never import `.server.ts` files in client code
+- Use `VITE_` prefix for client-accessible variables
+- Validate at startup to fail fast on misconfiguration
+- Use Zod or similar for runtime validation
+- Keep secrets out of error messages and logs
+- Consider using `.env.local` for local overrides (gitignored)

package/vendor/skills/skills/tanstack-start-best-practices/rules/err-server-errors.md

@@ -0,0 +1,189 @@
+# err-server-errors: Handle Server Function Errors
+
+## Priority: MEDIUM
+
+## Explanation
+
+Server function errors cross the network boundary. Handle them gracefully with appropriate error types, status codes, and user-friendly messages. Avoid exposing internal details in production.
+
+## Bad Example
+
+```tsx
+// Throwing raw errors - exposes internals
+export const createUser = createServerFn({ method: "POST" })
+  .validator(createUserSchema)
+  .handler(async ({ data }) => {
+    const user = await db.users.create({ data }); // May throw DB error
+    return user;
+    // Prisma error with stack trace sent to client
+  });
+
+// Generic error handling - no useful info for client
+export const getPost = createServerFn().handler(async ({ data }) => {
+  try {
+    return await fetchPost(data.id);
+  } catch (e) {
+    throw new Error("Something went wrong"); // Too vague
+  }
+});
+```
+
+## Good Example: Structured Error Handling
+
+```tsx
+// lib/errors.ts
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public status: number = 400
+  ) {
+    super(message);
+    this.name = "AppError";
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super(`${resource} not found`, "NOT_FOUND", 404);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = "Unauthorized") {
+    super(message, "UNAUTHORIZED", 401);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(
+    message: string,
+    public fields?: Record<string, string>
+  ) {
+    super(message, "VALIDATION_ERROR", 400);
+  }
+}
+```
+
+## Good Example: Server Function with Error Handling
+
+```tsx
+import { createServerFn, notFound } from "@tanstack/react-start";
+import { setResponseStatus } from "@tanstack/react-start/server";
+
+export const getPost = createServerFn()
+  .validator(z.object({ id: z.string() }))
+  .handler(async ({ data }) => {
+    const post = await db.posts.findUnique({
+      where: { id: data.id },
+    });
+
+    if (!post) {
+      // Use built-in notFound for 404s
+      throw notFound();
+    }
+
+    return post;
+  });
+
+export const createPost = createServerFn({ method: "POST" })
+  .validator(createPostSchema)
+  .handler(async ({ data }) => {
+    try {
+      const post = await db.posts.create({ data });
+      return post;
+    } catch (error) {
+      if (error instanceof Prisma.PrismaClientKnownRequestError) {
+        if (error.code === "P2002") {
+          // Unique constraint violation
+          setResponseStatus(409);
+          throw new AppError("A post with this title already exists", "DUPLICATE", 409);
+        }
+      }
+
+      // Log full error server-side
+      console.error("Failed to create post:", error);
+
+      // Return sanitized error to client
+      setResponseStatus(500);
+      throw new AppError("Failed to create post", "INTERNAL_ERROR", 500);
+    }
+  });
+```
+
+## Good Example: Client-Side Error Handling
+
+```tsx
+function CreatePostForm() {
+  const [error, setError] = useState<string | null>(null);
+
+  const createMutation = useMutation({
+    mutationFn: createPost,
+    onError: error => {
+      if (error instanceof AppError) {
+        setError(error.message);
+      } else if (error instanceof ValidationError) {
+        // Handle field-specific errors
+        Object.entries(error.fields ?? {}).forEach(([field, message]) => {
+          form.setError(field, { message });
+        });
+      } else {
+        setError("An unexpected error occurred");
+      }
+    },
+    onSuccess: post => {
+      navigate({ to: "/posts/$postId", params: { postId: post.id } });
+    },
+  });
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {error && <Alert variant="error">{error}</Alert>}
+      {/* form fields */}
+    </form>
+  );
+}
+```
+
+## Good Example: Using Redirects for Auth Errors
+
+```tsx
+export const updateProfile = createServerFn({ method: "POST" })
+  .validator(updateProfileSchema)
+  .handler(async ({ data }) => {
+    const session = await getSessionData();
+
+    if (!session) {
+      // Redirect to login for auth errors
+      throw redirect({
+        to: "/login",
+        search: { redirect: "/settings" },
+      });
+    }
+
+    return await db.users.update({
+      where: { id: session.userId },
+      data,
+    });
+  });
+```
+
+## Error Response Best Practices
+
+| Scenario             | HTTP Status | Response                     |
+| -------------------- | ----------- | ---------------------------- |
+| Validation failed    | 400         | Field-specific errors        |
+| Not authenticated    | 401         | Redirect to login            |
+| Not authorized       | 403         | Generic forbidden message    |
+| Resource not found   | 404         | Use `notFound()`             |
+| Conflict (duplicate) | 409         | Specific conflict message    |
+| Server error         | 500         | Generic message, log details |
+
+## Context
+
+- Use `notFound()` for 404 errors - integrates with router
+- Use `redirect()` for auth-related errors
+- Set status codes with `setResponseStatus()`
+- Log full errors server-side, sanitize for client
+- Create custom error classes for consistent handling
+- Validation errors from `.validator()` are automatic