scale-stack 0.0.1-alpha.2 → 0.0.2

package/templates/i18n/request.ts.ejs

@@ -0,0 +1,15 @@
+import { getRequestConfig } from "next-intl/server";
+import { hasLocale } from "next-intl";
+import { routing } from "./routing";
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  const requested = await requestLocale;
+  const locale = hasLocale(routing.locales, requested)
+    ? requested
+    : routing.defaultLocale;
+
+  return {
+    locale,
+    messages: (await import(`../../messages/${locale}.json`)).default,
+  };
+});

package/templates/i18n/routing.ts.ejs

@@ -0,0 +1,7 @@
+import { defineRouting } from "next-intl/routing";
+
+export const routing = defineRouting({
+  locales: ["en", "ar"],
+  defaultLocale: "en",
+  localePrefix: "always",
+});

package/templates/orm/prisma.config.ts.ejs

@@ -0,0 +1,12 @@
+import "dotenv/config";
+import { defineConfig, env } from "prisma/config";
+
+export default defineConfig({
+  schema: "prisma/schema.prisma",
+  migrations: {
+    path: "prisma/migrations",
+  },
+  datasource: {
+    url: env("DATABASE_URL"),
+  },
+});

package/templates/orm/prisma.ts.ejs

@@ -0,0 +1,17 @@
+import { env } from "@/env";
+import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "../../prisma/generated/client";
+
+const globalForPrisma = globalThis as unknown as {
+  prisma?: PrismaClient;
+};
+
+export const prisma =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    adapter: new PrismaPg({ connectionString: env.DATABASE_URL }),
+  });
+
+if (process.env.NODE_ENV !== "production") {
+  globalForPrisma.prisma = prisma;
+}

package/templates/orm/schema.prisma.ejs

@@ -0,0 +1,8 @@
+generator client {
+  provider = "prisma-client"
+  output   = "./generated"
+}
+
+datasource db {
+  provider = "postgresql"
+}

package/templates/pre-commit/prek.toml.ejs

@@ -0,0 +1,35 @@
+# --- Built-in fast hooks (offline, zero setup) ---
+[[repos]]
+repo = "builtin"
+hooks = [
+  { id = "trailing-whitespace" },
+  { id = "end-of-file-fixer" },
+  { id = "check-yaml" },
+  { id = "check-json" },
+]
+
+# --- Local project hooks (use package.json scripts) ---
+[[repos]]
+repo = "local"
+
+[[repos.hooks]]
+id = "eslint"
+name = "eslint"
+language = "system"
+entry = "pnpm lint"
+files = { glob = "*.{ts,tsx,js,jsx,mjs}" }
+pass_filenames = false
+
+[[repos.hooks]]
+id = "prettier"
+name = "prettier"
+language = "system"
+entry = "pnpm format"
+files = { glob = "*.{ts,tsx,js,jsx,json,css,md}" }
+
+[[repos.hooks]]
+id = "typecheck"
+name = "typecheck"
+language = "system"
+entry = "pnpm typecheck"
+pass_filenames = false

package/templates/proxy/proxy.ts.ejs

@@ -0,0 +1,81 @@
+import type { NextRequest } from "next/server";
+<% if (hasAuth || !hasI18n) { %>
+import { NextResponse } from "next/server";
+<% } %>
+<% if (hasI18n) { %>import createMiddleware from "next-intl/middleware";
+<% } %><% if (hasAuth) { %>import { getSessionCookie } from "better-auth/cookies";
+<% } %><% if (hasI18n) { %>import { routing } from "./i18n/routing";
+<% if (hasAuth) { %>import { getPathname } from "./i18n/navigation";
+<% } %><% } %>
+<% if (hasI18n) { %>const intlProxy = createMiddleware(routing);
+
+<% } %><% if (hasAuth) { %>const PROTECTED_ROUTE_PREFIXES = ["/dashboard"] as const;
+
+function normalizePathname(pathname: string): string {
+<% if (hasI18n) { %>  const [, maybeLocale, ...rest] = pathname.split("/");
+  const normalizedPathname = routing.locales.some(
+    (locale) => locale === maybeLocale,
+  )
+    ? `/${rest.join("/")}`
+    : pathname;
+
+<% } else { %>  const normalizedPathname = pathname;
+<% } %>  return normalizedPathname === "/"
+    ? "/"
+    : normalizedPathname.replace(/\/$/, "");
+}
+
+function isProtectedRoute(pathname: string): boolean {
+  const normalizedPathname = normalizePathname(pathname);
+
+  return PROTECTED_ROUTE_PREFIXES.some(
+    (prefix) =>
+      normalizedPathname === prefix ||
+      normalizedPathname.startsWith(`${prefix}/`),
+  );
+}
+
+function buildSignInUrl(request: NextRequest): URL {
+  const url = request.nextUrl.clone();
+<% if (hasI18n) { %>  const [, maybeLocale] = request.nextUrl.pathname.split("/");
+  const locale =
+    routing.locales.find((item) => item === maybeLocale) ??
+    routing.defaultLocale;
+
+  url.pathname = getPathname({ locale, href: "/sign-in" });
+<% } else { %>  url.pathname = "/sign-in";
+<% } %>  url.searchParams.set(
+    "callbackUrl",
+    `${request.nextUrl.pathname}${request.nextUrl.search}`,
+  );
+  return url;
+}
+
+function authProxy(request: NextRequest): NextResponse | null {
+  if (!isProtectedRoute(request.nextUrl.pathname)) {
+    return null;
+  }
+
+  // This proxy check is only for fast redirects; validate the session again
+  // before reading protected data in pages, route handlers, and actions.
+  if (getSessionCookie(request)) {
+    return null;
+  }
+
+  return NextResponse.redirect(buildSignInUrl(request));
+}
+
+<% } %>export default function proxy(<% if (hasAuth || hasI18n) { %>request<% } else { %>_request<% } %>: NextRequest) {
+<% if (hasAuth) { %>  const authResponse = authProxy(request);
+
+  if (authResponse) {
+    return authResponse;
+  }
+
+<% } %><% if (hasI18n) { %>  return intlProxy(request);
+<% } else { %>  return NextResponse.next();
+<% } %>}
+
+export const config = {
+  matcher: "/((?!api|trpc|_next|_vercel|.*\\..*).*)",
+};

package/templates/server-actions/safe-action.ts.ejs

@@ -0,0 +1,51 @@
+import { createSafeActionClient } from "next-safe-action";
+<% if (hasAuth) { %>import { betterAuth } from "@next-safe-action/adapter-better-auth";
+import { auth } from "@/lib/auth";
+<% } %>import { z } from "zod";
+
+const actionMetadataSchema = z.object({
+  actionName: z.string().min(1),
+});
+
+type ActionMetadata = z.infer<typeof actionMetadataSchema>;
+type ActionOutcome = "success" | "error";
+
+function logAction(
+  metadata: ActionMetadata | undefined,
+  durationMs: number,
+  outcome: ActionOutcome,
+): void {
+  console.info("[safe-action]", {
+    actionName: metadata?.actionName ?? "unknown",
+    durationMs,
+    outcome,
+  });
+}
+export const actionClient = createSafeActionClient({
+  defaultValidationErrorsShape: "flattened",
+  defineMetadataSchema() {
+    return actionMetadataSchema;
+  },
+  handleServerError(error, { metadata }) {
+    console.error("[safe-action] server error", {
+      actionName: metadata?.actionName ?? "unknown",
+      error,
+    });
+
+    return "Something went wrong. Please try again.";
+  },
+}).use(async ({ next, metadata }) => {
+  const startedAt = performance.now();
+
+  try {
+    const result = await next();
+    logAction(metadata, Math.round(performance.now() - startedAt), "success");
+    return result;
+  } catch (error) {
+    logAction(metadata, Math.round(performance.now() - startedAt), "error");
+    throw error;
+  }
+});
+<% if (hasAuth) { %>
+export const authActionClient = actionClient.use(betterAuth(auth));
+<% } %>

package/templates/ui/client-side-wrappers.tsx.ejs

@@ -0,0 +1,19 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { NuqsAdapter } from "nuqs/adapters/next/app";
+import { Toaster } from "@/components/ui/sonner";
+import { TooltipProvider } from "@/components/ui/tooltip";
+<% if (hasAnalyticsProvider) { %>import { AnalyticsProvider } from "./analytics-provider";
+<% } %>
+
+export function ClientSideWrappers({ children }: { children: ReactNode }) {
+  return (
+    <NuqsAdapter>
+      <TooltipProvider>
+        <% if (hasAnalyticsProvider) { %><AnalyticsProvider>{children}</AnalyticsProvider><% } else { %>{children}<% } %>
+        <Toaster />
+      </TooltipProvider>
+    </NuqsAdapter>
+  );
+}

package/templates/ui/page.tsx.ejs

@@ -0,0 +1,117 @@
+<% if (i18n) { %>import { getTranslations } from "next-intl/server";
+import type { Locale } from "next-intl";
+import { Link } from "@/i18n/navigation";
+<% } else { %>import Link from "next/link";
+<% } %>import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+
+<% if (i18n) { %>type HomeProps = Readonly<{
+  params: Promise<{ locale: Locale }>;
+}>;
+
+<% } %>export default <% if (i18n) { %>async <% } %>function Home(<% if (i18n) { %>{ params }: HomeProps<% } %>) {
+<% if (i18n) { %>  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "Home" });
+
+<% } %>
+  return (
+    <main className="relative flex flex-1 flex-col overflow-hidden px-6 py-16">
+      <div className="absolute inset-0 -z-10 bg-[radial-gradient(circle_at_top_left,var(--muted),transparent_34rem),radial-gradient(circle_at_bottom_right,var(--accent),transparent_28rem)]" />
+      <section className="mx-auto flex w-full max-w-6xl flex-col gap-10">
+        <div className="max-w-3xl space-y-6">
+          <p className="text-sm font-medium tracking-[0.2em] text-muted-foreground uppercase">
+            <% if (i18n) { %>{t("eyebrow")}<% } else { %>Scale Stack<% } %>
+          </p>
+          <div className="space-y-4">
+            <h1 className="max-w-3xl text-4xl font-semibold tracking-tight text-balance sm:text-6xl">
+              <%= projectName %>
+            </h1>
+            <p className="max-w-2xl text-lg text-muted-foreground text-balance">
+              <% if (i18n) { %>{t("description")}<% } else { %>Your app is wired with shadcn/ui, Tailwind CSS 4, typed server
+              actions, form handling, and the Scale Stack guardrails agents
+              need to keep moving safely.<% } %>
+            </p>
+          </div>
+        </div>
+
+        <div className="space-y-3">
+          <div>
+            <h2 className="text-2xl font-semibold tracking-tight">
+              <% if (i18n) { %>{t("explorePages")}<% } else { %>Explore generated pages<% } %>
+            </h2>
+            <p className="text-muted-foreground">
+              <% if (i18n) { %>{t("explorePagesDescription")}<% } else { %>Each card links to a real route in this scaffold.<% } %>
+            </p>
+          </div>
+          <div className="grid gap-4 md:grid-cols-2<% if (hasAuth && hasAiChat) { %> xl:grid-cols-4<% } else { %> xl:grid-cols-3<% } %>">
+          <Card className="transition-colors hover:border-primary/50">
+            <CardHeader>
+              <CardTitle><% if (i18n) { %>{t("dashboard")}<% } else { %>Dashboard<% } %></CardTitle>
+              <CardDescription>
+                <% if (i18n) { %>{t("dashboardCardDescription")}<% } else { %>Try the generated React Hook Form example backed by Zod,
+                shadcn/ui fields, and next-safe-action.<% } %>
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Button asChild variant="secondary">
+                <Link href="/dashboard"><% if (i18n) { %>{t("exploreForms")}<% } else { %>Explore forms<% } %></Link>
+              </Button>
+            </CardContent>
+          </Card>
+<% if (hasAiChat) { %>
+          <Card className="transition-colors hover:border-primary/50">
+            <CardHeader>
+              <CardTitle><% if (i18n) { %>{t("aiChat")}<% } else { %>AI chat<% } %></CardTitle>
+              <CardDescription>
+                <% if (i18n) { %>{t("aiChatCardDescription")}<% } else { %>Open the provider-free AI Elements mock and see the AI SDK
+                transport contract ready for your backend.<% } %>
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Button asChild variant="secondary">
+                <Link href="/chat"><% if (i18n) { %>{t("openChat")}<% } else { %>Open chat<% } %></Link>
+              </Button>
+            </CardContent>
+          </Card>
+<% } %><% if (hasAuth) { %>
+          <Card className="transition-colors hover:border-primary/50">
+            <CardHeader>
+              <CardTitle><% if (i18n) { %>{t("signIn")}<% } else { %>Sign in<% } %></CardTitle>
+              <CardDescription>
+                <% if (i18n) { %>{t("<% if (isStatefulAuth) { %>signInStatefulCardDescription<% } else { %>signInCardDescription<% } %>")}<% } else { %>Exercise Better Auth with Microsoft Entra OAuth<% if (isStatefulAuth) { %>
+                and Prisma-backed email/password sessions<% } %>.<% } %>
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Button asChild variant="secondary">
+                <Link href="/sign-in"><% if (i18n) { %>{t("signIn")}<% } else { %>Sign in<% } %></Link>
+              </Button>
+            </CardContent>
+          </Card>
+          <Card className="transition-colors hover:border-primary/50">
+            <CardHeader>
+              <CardTitle><% if (i18n) { %>{t("signUp")}<% } else { %>Sign up<% } %></CardTitle>
+              <CardDescription>
+                <% if (i18n) { %>{t("signUpCardDescription")}<% } else { %>Create an account through the same Better Auth setup and keep
+                the onboarding route ready for customization.<% } %>
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Button asChild variant="secondary">
+                <Link href="/sign-up"><% if (i18n) { %>{t("signUp")}<% } else { %>Sign up<% } %></Link>
+              </Button>
+            </CardContent>
+          </Card>
+<% } %>
+          </div>
+        </div>
+      </section>
+    </main>
+  );
+}

package/templates/utility-libs/date-fns.SKILL.md.ejs

@@ -0,0 +1,34 @@
+---
+name: date-fns
+description: Use date-fns for date parsing, formatting, comparison, and arithmetic in this project. Use when working with dates, durations, calendars, relative time, or locale-aware date formatting.
+---
+
+# date-fns
+
+## Instructions
+
+- Use focused function imports from `date-fns`, for example `import { format, parseISO } from "date-fns"`.
+- Keep parsing explicit. Use `parseISO` for ISO strings instead of relying on ambiguous `Date` parsing.
+- Treat `Date` values as values passed between helpers. Do not mutate dates in place.
+- Prefer date-fns helpers for comparison and arithmetic instead of manual millisecond math.
+- Use locale-aware formatting when user-facing dates need localization.
+
+## Common Patterns
+
+```ts
+import { format, isAfter, parseISO } from "date-fns";
+
+const dueDate = parseISO(task.dueAt);
+const isOverdue = isAfter(new Date(), dueDate);
+const label = format(dueDate, "PPP");
+```
+
+For business rules, keep date operations near the domain logic and name the intent:
+
+```ts
+import { addDays, startOfDay } from "date-fns";
+
+export function trialEndsAt(startedAt: Date): Date {
+  return startOfDay(addDays(startedAt, 14));
+}
+```

package/templates/utility-libs/motion.SKILL.md.ejs

@@ -0,0 +1,234 @@
+---
+name: motion
+description: Use Motion for React animations in this project. Use when adding or changing React animations, gestures, layout animations, page transitions, scroll effects, or exit animations with the `motion` package.
+---
+
+# Motion
+
+## When To Use Motion
+
+Use Motion when the UI needs React-aware animation:
+
+- State-driven animations linked to component props or state.
+- Cross-device gestures such as hover, tap, focus, drag, and in-view effects.
+- Enter and exit animations for conditionally rendered UI.
+- Layout animations, shared element transitions, reorderable lists, or expanding panels.
+- Coordinated parent/child sequences, staggered reveals, or keyframes.
+- Scroll-triggered and scroll-linked animation.
+- SVG path, shape, or attribute animation.
+
+Use CSS transitions instead for a simple, isolated effect like a color change on hover.
+
+## Project Rules
+
+- Import React APIs from `motion/react`.
+- In the Next.js App Router, put interactive Motion usage in Client Components. Add `"use client"` when using Motion hooks, gestures, state, event handlers, or browser-only APIs.
+- Prefer transforms and opacity for smooth animation. Use `layout` for layout changes instead of manually animating layout properties.
+- Keep animation targets readable and typed. Extract repeated variants/transitions into local constants near the component that owns them.
+- Respect reduced motion. Replace large transform, parallax, and autoplaying motion with opacity or static alternatives.
+- Avoid adding another animation library unless Motion cannot solve the requirement.
+
+## Import Guide
+
+```tsx
+import {
+  AnimatePresence,
+  MotionConfig,
+  motion,
+  stagger,
+  useAnimate,
+  useReducedMotion,
+  useScroll,
+  useTransform,
+} from "motion/react";
+```
+
+Use only what you need so the package can stay tree-shakable.
+
+## Decision Guide
+
+- One element changes with state: use `animate`, `initial`, and `transition`.
+- Hover/tap/focus/drag/in-view behavior: use `whileHover`, `whileTap`, `whileFocus`, `whileDrag`, or `whileInView`.
+- Element leaves the React tree: wrap the conditional region in `AnimatePresence` and define `exit`.
+- Parent and children need coordination: use `variants`, `stagger`, `delayChildren`, and `when`.
+- Element size or position changes: use `layout`; use `layoutId` for shared element transitions.
+- Animation must run from an event or sequence outside render state: use `useAnimate`.
+- Animation follows scroll: use `useScroll` and `useTransform`, with a reduced-motion fallback.
+
+## Patterns
+
+### Microinteraction
+
+```tsx
+"use client";
+
+import { motion } from "motion/react";
+
+export function SaveButton() {
+  return (
+    <motion.button
+      whileHover={{ scale: 1.03 }}
+      whileTap={{ scale: 0.97 }}
+      transition={{ type: "spring", stiffness: 500, damping: 30 }}
+    >
+      Save
+    </motion.button>
+  );
+}
+```
+
+### Enter And Exit
+
+Use `AnimatePresence` when elements leave the React tree. Give exiting children stable keys.
+
+```tsx
+"use client";
+
+import { AnimatePresence, motion } from "motion/react";
+
+export function Toast({ message }: { message?: string }) {
+  return (
+    <AnimatePresence>
+      {message ? (
+        <motion.div
+          key={message}
+          initial={{ opacity: 0, y: 8 }}
+          animate={{ opacity: 1, y: 0 }}
+          exit={{ opacity: 0, y: -8 }}
+        >
+          {message}
+        </motion.div>
+      ) : null}
+    </AnimatePresence>
+  );
+}
+```
+
+### Staggered Lists
+
+Use variants when child animations should be coordinated by the parent.
+
+```tsx
+"use client";
+
+import { motion, stagger } from "motion/react";
+
+const list = {
+  hidden: { opacity: 0 },
+  visible: {
+    opacity: 1,
+    transition: { delayChildren: stagger(0.06), when: "beforeChildren" },
+  },
+};
+
+const item = {
+  hidden: { opacity: 0, y: 8 },
+  visible: { opacity: 1, y: 0 },
+};
+
+export function ResultList({ results }: { results: string[] }) {
+  return (
+    <motion.ul initial="hidden" animate="visible" variants={list}>
+      {results.map((result) => (
+        <motion.li key={result} variants={item}>
+          {result}
+        </motion.li>
+      ))}
+    </motion.ul>
+  );
+}
+```
+
+### Layout Animation
+
+Use `layout` for size and position changes. Use `layoutId` only for intentional shared-element transitions.
+
+```tsx
+"use client";
+
+import { motion } from "motion/react";
+
+export function ExpandingCard({ expanded }: { expanded: boolean }) {
+  return (
+    <motion.article layout className={expanded ? "col-span-2" : undefined}>
+      <motion.h2 layout="position">Details</motion.h2>
+    </motion.article>
+  );
+}
+```
+
+### Scroll-Linked Animation
+
+Use Motion values for scroll-linked transforms, and disable physical movement for reduced-motion users.
+
+```tsx
+"use client";
+
+import {
+  motion,
+  useReducedMotion,
+  useScroll,
+  useTransform,
+} from "motion/react";
+
+export function ReadingProgress() {
+  const shouldReduceMotion = useReducedMotion();
+  const { scrollYProgress } = useScroll();
+  const scaleX = useTransform(scrollYProgress, [0, 1], [0, 1]);
+
+  return (
+    <motion.div
+      aria-hidden="true"
+      style={{ scaleX: shouldReduceMotion ? 1 : scaleX }}
+      className="fixed inset-x-0 top-0 h-1 origin-left"
+    />
+  );
+}
+```
+
+### Imperative Sequence
+
+Reach for `useAnimate` only when declarative props or variants are not enough.
+
+```tsx
+"use client";
+
+import { useEffect } from "react";
+import { useAnimate } from "motion/react";
+
+export function IntroSequence() {
+  const [scope, animate] = useAnimate();
+
+  useEffect(() => {
+    const controls = animate([
+      ["h1", { opacity: [0, 1], y: [12, 0] }],
+      ["p", { opacity: [0, 1] }, { at: "-0.1" }],
+    ]);
+
+    return () => controls.stop();
+  }, [animate]);
+
+  return (
+    <section ref={scope}>
+      <h1>Welcome</h1>
+      <p>Everything is ready.</p>
+    </section>
+  );
+}
+```
+
+## Accessibility Checklist
+
+- Use `MotionConfig reducedMotion="user"` at an app or feature boundary when broad reduced-motion handling is appropriate.
+- Use `useReducedMotion()` for bespoke components.
+- Replace large `x`, `y`, `scale`, rotation, and parallax effects with opacity or static states when reduced motion is enabled.
+- Do not autoplay decorative videos or looping motion for reduced-motion users.
+- Keep focus states visible; do not replace focus indicators with motion-only feedback.
+
+## Performance Checklist
+
+- Prefer `opacity` and transforms (`x`, `y`, `scale`, `rotate`) for frequent animations.
+- Avoid animating CSS variables for high-frequency motion because it can trigger paint; prefer Motion values for dynamic transforms.
+- Use `layout` intentionally and sparingly in large lists.
+- Use keyframes for short expressive sequences; keep long-running or repeating animations subtle.
+- Use `initial={false}` when an entrance animation would cause distracting first paint or hydration movement.

package/templates/utility-libs/ts-pattern.SKILL.md.ejs

@@ -0,0 +1,44 @@
+---
+name: ts-pattern
+description: Use ts-pattern for exhaustive pattern matching in TypeScript. Use when handling discriminated unions, complex branching, nested data shapes, or replacing fragile switch/if chains.
+---
+
+# ts-pattern
+
+## Instructions
+
+- Import `match` and patterns from `ts-pattern`: `import { match, P } from "ts-pattern"`.
+- Prefer `match(value).with(...).exhaustive()` for closed discriminated unions so TypeScript verifies every case.
+- Keep union tags explicit and stable, such as `{ type: "success" }` or `{ status: "idle" }`.
+- Use `P` helpers for nested structures, guards, optionals, and wildcard cases when they improve readability.
+- Avoid using `.otherwise()` for closed unions unless there is a deliberate unknown fallback. Prefer `.exhaustive()`.
+
+## Common Patterns
+
+```ts
+import { match } from "ts-pattern";
+
+type Result =
+  | { type: "success"; value: string }
+  | { type: "error"; message: string }
+  | { type: "loading" };
+
+export function labelFor(result: Result): string {
+  return match(result)
+    .with({ type: "success" }, ({ value }) => value)
+    .with({ type: "error" }, ({ message }) => message)
+    .with({ type: "loading" }, () => "Loading...")
+    .exhaustive();
+}
+```
+
+Use patterns to make nested branching readable:
+
+```ts
+import { match, P } from "ts-pattern";
+
+const canEdit = match(user)
+  .with({ role: "admin" }, () => true)
+  .with({ role: "member", permissions: P.array("write") }, () => true)
+  .otherwise(() => false);
+```