blacksmith-cli 0.1.1

package/src/templates/frontend/src/router/index.tsx.hbs

@@ -0,0 +1,12 @@
+/**
+ * Router Setup
+ *
+ * Creates the browser router from the route configuration.
+ * Generated by Blacksmith. You own this file — customize as needed.
+ */
+
+import { createBrowserRouter } from 'react-router-dom'
+import { routes } from './routes'
+
+export { Path, buildPath } from './paths'
+export const router = createBrowserRouter(routes)

package/src/templates/frontend/src/router/layouts/auth-layout.tsx.hbs

@@ -0,0 +1,68 @@
+import { Outlet, Link } from 'react-router-dom'
+import { Separator, Button } from '@blacksmith-ui/react'
+import { Anvil } from 'lucide-react'
+import { Path } from '@/router/paths'
+
+export function AuthLayoutWrapper() {
+  return (
+    <div className="grid min-h-screen grid-cols-1 lg:grid-cols-2">
+      {/* Left Column — Branding Panel */}
+      <div className="hidden lg:flex flex-col justify-between bg-primary text-primary-foreground p-10">
+        <div className="flex items-center gap-2">
+          <Anvil className="h-6 w-6" />
+          <span className="text-lg font-semibold">{{projectName}}</span>
+        </div>
+
+        <div className="flex flex-col items-center gap-4">
+          <blockquote className="text-2xl font-medium">
+            &ldquo;Build faster. Ship with confidence.&rdquo;
+          </blockquote>
+          <p className="text-primary-foreground/70">
+            A fullstack platform powered by Django, React, and Blacksmith.
+          </p>
+        </div>
+
+        <p className="text-sm text-primary-foreground/50">
+          &copy; {new Date().getFullYear()} {{projectName}}. All rights reserved.
+        </p>
+      </div>
+
+      {/* Right Column — Auth Form */}
+      <div className="flex flex-col">
+        <div className="flex items-center justify-between p-6 lg:p-8">
+          <div className="flex items-center gap-2 lg:hidden">
+            <Anvil className="h-5 w-5" />
+            <span className="font-semibold">{{projectName}}</span>
+          </div>
+          <div className="lg:ml-auto">
+            <Button variant="ghost" size="sm" asChild>
+              <Link to={Path.Home}>Back to Home</Link>
+            </Button>
+          </div>
+        </div>
+
+        <div className="flex flex-1 items-center justify-center px-6 pb-10">
+          <div className="w-full max-w-[420px]">
+            <Outlet />
+          </div>
+        </div>
+
+        <Separator />
+
+        <div className="flex items-center justify-center gap-4 p-6">
+          <Button variant="link" size="sm" className="text-muted-foreground" asChild>
+            <Link to="/terms">Terms</Link>
+          </Button>
+          <Separator orientation="vertical" className="h-4" />
+          <Button variant="link" size="sm" className="text-muted-foreground" asChild>
+            <Link to="/privacy">Privacy</Link>
+          </Button>
+          <Separator orientation="vertical" className="h-4" />
+          <Button variant="link" size="sm" className="text-muted-foreground" asChild>
+            <Link to="/support">Support</Link>
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/templates/frontend/src/router/layouts/main-layout.tsx.hbs

@@ -0,0 +1,137 @@
+import { Outlet, Link, useNavigate } from 'react-router-dom'
+import { Path } from '@/router/paths'
+import {
+  Button,
+  Separator,
+  Tooltip,
+  DropdownMenuPrimitives,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuLabel,
+  Avatar,
+  AvatarFallback,
+} from '@blacksmith-ui/react'
+import { LogOut, User, Settings, Sun, Moon, Anvil } from 'lucide-react'
+import { useAuth } from '@/features/auth/hooks/use-auth'
+import { useDarkMode } from '@blacksmith-ui/react'
+
+function getInitials(user: any): string {
+  if (user?.displayName) {
+    const parts = user.displayName.split(' ')
+    const first = parts[0]?.[0] || ''
+    const last = parts[1]?.[0] || ''
+    return (first + last).toUpperCase()
+  }
+  return user?.email?.[0]?.toUpperCase() || 'U'
+}
+
+export function MainLayout() {
+  const { user, isAuthenticated, logout } = useAuth()
+  const { isDark, toggle } = useDarkMode()
+  const navigate = useNavigate()
+
+  const handleLogout = () => {
+    logout()
+    navigate(Path.Login)
+  }
+
+  return (
+    <div className="flex min-h-screen flex-col bg-background">
+      <header className="sticky top-0 z-50 w-full border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+        <div className="max-w-7xl mx-auto flex h-14 items-center px-4 sm:px-6 lg:px-8">
+          <Link to={Path.Home} className="flex items-center gap-2 mr-6">
+            <Anvil className="h-5 w-5" />
+            <span className="text-lg font-semibold tracking-tight">{{projectName}}</span>
+          </Link>
+
+          <div className="flex-1" />
+
+          <div className="flex items-center gap-2">
+            <Tooltip content={isDark ? 'Light mode' : 'Dark mode'}>
+              <Button variant="ghost" size="icon" onClick={toggle}>
+                {isDark ? <Sun className="h-4 w-4" /> : <Moon className="h-4 w-4" />}
+              </Button>
+            </Tooltip>
+
+            {isAuthenticated ? (
+              <DropdownMenuPrimitives.Root>
+                <DropdownMenuTrigger asChild>
+                  <Button variant="ghost" className="relative h-8 w-8 rounded-full">
+                    <Avatar className="h-8 w-8">
+                      <AvatarFallback className="text-xs">
+                        {getInitials(user)}
+                      </AvatarFallback>
+                    </Avatar>
+                  </Button>
+                </DropdownMenuTrigger>
+                <DropdownMenuContent align="end" className="w-56">
+                  <DropdownMenuLabel className="font-normal">
+                    <div className="flex flex-col space-y-1">
+                      <p className="text-sm font-medium leading-none">
+                        {user?.displayName || 'User'}
+                      </p>
+                      <p className="text-xs leading-none text-muted-foreground">
+                        {user?.email}
+                      </p>
+                    </div>
+                  </DropdownMenuLabel>
+                  <DropdownMenuSeparator />
+                  <DropdownMenuItem>
+                    <User className="mr-2 h-4 w-4" />
+                    Profile
+                  </DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <Settings className="mr-2 h-4 w-4" />
+                    Settings
+                  </DropdownMenuItem>
+                  <DropdownMenuSeparator />
+                  <DropdownMenuItem onClick={handleLogout}>
+                    <LogOut className="mr-2 h-4 w-4" />
+                    Sign Out
+                  </DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenuPrimitives.Root>
+            ) : (
+              <>
+                <Button variant="ghost" size="sm" asChild>
+                  <Link to={Path.Login}>Sign In</Link>
+                </Button>
+                <Button size="sm" asChild>
+                  <Link to={Path.Register}>Sign Up</Link>
+                </Button>
+              </>
+            )}
+          </div>
+        </div>
+      </header>
+
+      <main className="flex-1 max-w-7xl w-full mx-auto px-4 sm:px-6 lg:px-8 py-8">
+        <Outlet />
+      </main>
+
+      <footer className="border-t">
+        <div className="max-w-7xl mx-auto flex flex-col items-center gap-4 px-4 py-6 sm:flex-row sm:justify-between sm:px-6 lg:px-8">
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <Anvil className="h-4 w-4" />
+            <span>&copy; {new Date().getFullYear()} {{projectName}}. All rights reserved.</span>
+          </div>
+          <div className="flex items-center gap-4">
+            <Button variant="link" size="sm" className="text-muted-foreground h-auto p-0" asChild>
+              <Link to="/terms">Terms</Link>
+            </Button>
+            <Separator orientation="vertical" className="h-4" />
+            <Button variant="link" size="sm" className="text-muted-foreground h-auto p-0" asChild>
+              <Link to="/privacy">Privacy</Link>
+            </Button>
+            <Separator orientation="vertical" className="h-4" />
+            <Button variant="link" size="sm" className="text-muted-foreground h-auto p-0" asChild>
+              <Link to="/support">Support</Link>
+            </Button>
+          </div>
+        </div>
+      </footer>
+    </div>
+  )
+}

package/src/templates/frontend/src/router/paths.ts.hbs

@@ -0,0 +1,38 @@
+/**
+ * Application Route Paths
+ *
+ * Central registry of all route paths used in the application.
+ * Use these enums instead of hardcoded strings for type-safe navigation.
+ *
+ * Generated by Blacksmith. You own this file — customize as needed.
+ */
+
+export enum Path {
+  Home = '/',
+  Login = '/login',
+  Register = '/register',
+  ForgotPassword = '/forgot-password',
+  ResetPassword = '/reset-password/:token',
+  Dashboard = '/dashboard',
+  // blacksmith:path
+}
+
+/**
+ * Build a path with dynamic parameters replaced.
+ *
+ * @example
+ *   buildPath(Path.ResetPassword, { token: 'abc123' })
+ *   // => '/reset-password/abc123'
+ */
+export function buildPath(
+  path: Path,
+  params?: Record<string, string>,
+): string {
+  let result: string = path
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      result = result.replace(`:${key}`, encodeURIComponent(value))
+    }
+  }
+  return result
+}

package/src/templates/frontend/src/router/routes.tsx.hbs

@@ -0,0 +1,64 @@
+/**
+ * Application Routes
+ *
+ * Assembles route objects exported from each page/feature.
+ * Each page owns its own routes — this file just composes them.
+ *
+ * Generated by Blacksmith. You own this file — customize as needed.
+ */
+
+import { Outlet, type RouteObject } from 'react-router-dom'
+import { AuthGuard } from '@/router/auth-guard'
+import { MainLayout } from '@/router/layouts/main-layout'
+import { AuthLayoutWrapper } from '@/router/layouts/auth-layout'
+import { RouteErrorBoundary } from '@/router/error-boundary'
+import NotFoundPage from '@/shared/components/not-found-page'
+import { homeRoutes } from '@/pages/home'
+import { dashboardRoutes } from '@/pages/dashboard'
+import { authRoutes } from '@/features/auth'
+// blacksmith:import
+
+/**
+ * Public routes — accessible without authentication.
+ */
+const publicRoutes: RouteObject[] = [
+  ...homeRoutes,
+]
+
+/**
+ * Private routes — wrapped in AuthGuard, requires authentication.
+ * Add your authenticated routes here.
+ */
+const privateRoutes: RouteObject[] = [
+  ...dashboardRoutes,
+  // blacksmith:routes
+]
+
+export const routes: RouteObject[] = [
+  // Auth pages (login, register, etc.)
+  {
+    element: <AuthLayoutWrapper />,
+    errorElement: <RouteErrorBoundary />,
+    children: authRoutes,
+  },
+
+  // App pages
+  {
+    element: <MainLayout />,
+    errorElement: <RouteErrorBoundary />,
+    children: [
+      ...publicRoutes,
+      {
+        element: (
+          <AuthGuard>
+            <Outlet />
+          </AuthGuard>
+        ),
+        children: privateRoutes,
+      },
+    ],
+  },
+
+  // Catch-all 404
+  { path: '*', element: <NotFoundPage /> },
+]

package/src/templates/frontend/src/shared/components/loading-spinner.tsx.hbs

@@ -0,0 +1,20 @@
+import { Spinner } from '@blacksmith-ui/react'
+
+interface LoadingSpinnerProps {
+  size?: 'sm' | 'md' | 'lg'
+  className?: string
+}
+
+const sizeMap = {
+  sm: 'h-4 w-4',
+  md: 'h-8 w-8',
+  lg: 'h-12 w-12',
+}
+
+export function LoadingSpinner({ size = 'md', className = '' }: LoadingSpinnerProps) {
+  return (
+    <div className={`flex items-center justify-center ${className}`}>
+      <Spinner className={sizeMap[size]} />
+    </div>
+  )
+}

package/src/templates/frontend/src/shared/components/not-found-page.tsx.hbs

@@ -0,0 +1,31 @@
+import { useNavigate } from 'react-router-dom'
+import { Button } from '@blacksmith-ui/react'
+import { ArrowLeft, FileQuestion } from 'lucide-react'
+import { Path } from '@/router/paths'
+
+export default function NotFoundPage() {
+  const navigate = useNavigate()
+
+  return (
+    <div className="flex items-center justify-center min-h-screen bg-background">
+      <div className="text-center space-y-4">
+        <div className="flex justify-center">
+          <div className="flex h-20 w-20 items-center justify-center rounded-full bg-muted">
+            <FileQuestion className="h-10 w-10 text-muted-foreground" />
+          </div>
+        </div>
+        <h1 className="text-5xl font-bold tracking-tight">404</h1>
+        <p className="text-xl text-muted-foreground">Page not found</p>
+        <p className="text-sm text-muted-foreground max-w-sm mx-auto">
+          The page you're looking for doesn't exist or has been moved.
+        </p>
+        <div className="pt-2">
+          <Button onClick={() => navigate(Path.Home)}>
+            <ArrowLeft className="mr-2 h-4 w-4" />
+            Back to Home
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/templates/frontend/src/shared/hooks/api-error.ts.hbs

@@ -0,0 +1,147 @@
+/**
+ * API Error Parsing
+ *
+ * Parses Django REST Framework error responses into user-friendly messages.
+ * Generated by Blacksmith. You own this file — customize as needed.
+ */
+
+export interface ApiError {
+  status: number
+  message: string
+  fieldErrors: Record<string, string[]>
+}
+
+const HTTP_ERROR_MESSAGES: Record<number, string> = {
+  400: 'The request was invalid. Please check your input.',
+  401: 'You need to sign in to continue.',
+  403: 'You don\'t have permission to perform this action.',
+  404: 'The requested resource was not found.',
+  405: 'This action is not allowed.',
+  408: 'The request timed out. Please try again.',
+  409: 'This conflicts with an existing resource.',
+  429: 'Too many requests. Please slow down and try again.',
+  500: 'Something went wrong on our end. Please try again later.',
+  502: 'The server is temporarily unavailable. Please try again.',
+  503: 'The service is currently unavailable. Please try again later.',
+}
+
+/**
+ * Parse an error thrown by the API client into a structured ApiError.
+ *
+ * Handles DRF response shapes:
+ * - { "detail": "Error message" }
+ * - { "non_field_errors": ["Error 1", "Error 2"] }
+ * - { "field_name": ["Error 1"], "other_field": ["Error 2"] }
+ * - { "field_name": [{ "message": "...", "code": "..." }] }
+ * - Plain string responses
+ */
+export function parseApiError(error: unknown): ApiError {
+  const status = getStatusCode(error)
+  const body = getErrorBody(error)
+
+  if (!body) {
+    return {
+      status,
+      message: HTTP_ERROR_MESSAGES[status] || 'An unexpected error occurred.',
+      fieldErrors: {},
+    }
+  }
+
+  // String body
+  if (typeof body === 'string') {
+    return { status, message: body, fieldErrors: {} }
+  }
+
+  // Object body — parse DRF error shape
+  if (typeof body === 'object' && body !== null) {
+    const fieldErrors: Record<string, string[]> = {}
+    const generalMessages: string[] = []
+
+    for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
+      const messages = normalizeMessages(value)
+
+      if (key === 'detail') {
+        generalMessages.push(...messages)
+      } else if (key === 'non_field_errors') {
+        generalMessages.push(...messages)
+      } else {
+        fieldErrors[key] = messages
+      }
+    }
+
+    // If no general message was found, summarize field errors
+    const message =
+      generalMessages.length > 0
+        ? generalMessages.join(' ')
+        : Object.keys(fieldErrors).length > 0
+          ? 'Please fix the errors below.'
+          : HTTP_ERROR_MESSAGES[status] || 'An unexpected error occurred.'
+
+    return { status, message, fieldErrors }
+  }
+
+  return {
+    status,
+    message: HTTP_ERROR_MESSAGES[status] || 'An unexpected error occurred.',
+    fieldErrors: {},
+  }
+}
+
+/**
+ * Get a single human-readable error message from any error.
+ */
+export function getErrorMessage(error: unknown): string {
+  return parseApiError(error).message
+}
+
+function getStatusCode(error: unknown): number {
+  if (error && typeof error === 'object') {
+    // @hey-api/client-fetch error shape
+    if ('status' in error && typeof (error as any).status === 'number') {
+      return (error as any).status
+    }
+    // Nested response
+    if ('response' in error && (error as any).response?.status) {
+      return (error as any).response.status
+    }
+  }
+  return 0
+}
+
+function getErrorBody(error: unknown): unknown {
+  if (error && typeof error === 'object') {
+    // @hey-api/client-fetch puts parsed body in `error` or `body`
+    if ('error' in error && (error as any).error != null) {
+      return (error as any).error
+    }
+    if ('body' in error && (error as any).body != null) {
+      return (error as any).body
+    }
+    // Some shapes put it in `data`
+    if ('data' in error && (error as any).data != null) {
+      return (error as any).data
+    }
+  }
+  // Native Error
+  if (error instanceof Error) {
+    return error.message
+  }
+  return null
+}
+
+function normalizeMessages(value: unknown): string[] {
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => {
+      if (typeof item === 'string') return [item]
+      if (item && typeof item === 'object' && 'message' in item) {
+        return [String(item.message)]
+      }
+      return [String(item)]
+    })
+  }
+  if (value && typeof value === 'object' && 'message' in value) {
+    return [String((value as any).message)]
+  }
+  return [String(value)]
+}

package/src/templates/frontend/src/shared/hooks/use-api-mutation.ts.hbs

@@ -0,0 +1,88 @@
+/**
+ * useApiMutation — Enhanced useMutation for API calls
+ *
+ * Wraps TanStack useMutation with:
+ * - DRF error parsing with field-level and general error messages
+ * - Optional query invalidation after success
+ *
+ * Error state is derived from the mutation's own `error` — no local state.
+ *
+ * Usage:
+ *   const createPost = useApiMutation({
+ *     ...blogPostsCreateMutation(),
+ *     invalidateKeys: [blogPostsListQueryKey()],
+ *   })
+ *
+ *   // In a form submit handler:
+ *   createPost.mutate({ body: { title: 'Hello' } })
+ *
+ *   // Display the general error message:
+ *   {createPost.errorMessage && <Alert variant="destructive">{createPost.errorMessage}</Alert>}
+ *
+ *   // Access field errors for inline form display:
+ *   createPost.fieldErrors.title  // ["This field is required."]
+ *
+ * Generated by Blacksmith. You own this file — customize as needed.
+ */
+
+import {
+  useMutation,
+  useQueryClient,
+  type QueryKey,
+  type UseMutationOptions,
+  type UseMutationResult,
+} from '@tanstack/react-query'
+import { parseApiError, type ApiError } from './api-error'
+import { useMemo } from 'react'
+
+export interface UseApiMutationOptions<TData, TVariables, TOnMutateResult>
+  extends UseMutationOptions<TData, Error, TVariables, TOnMutateResult> {
+  /** Query keys to invalidate after a successful mutation */
+  invalidateKeys?: QueryKey[]
+}
+
+export type UseApiMutationResult<TData, TVariables, TOnMutateResult> =
+  UseMutationResult<TData, Error, TVariables, TOnMutateResult> & {
+    /** Parsed field-level errors from the last failed mutation (e.g. { email: ["Already exists."] }) */
+    fieldErrors: Record<string, string[]>
+    /** Parsed API error from the last failed mutation */
+    apiError: ApiError | null
+    /** Single error message string from the last failed mutation */
+    errorMessage: string | null
+  }
+
+export function useApiMutation<
+  TData = unknown,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: UseApiMutationOptions<TData, TVariables, TOnMutateResult>,
+): UseApiMutationResult<TData, TVariables, TOnMutateResult> {
+  const queryClient = useQueryClient()
+
+  const { invalidateKeys, ...mutationOptions } = options
+
+  const mutation = useMutation<TData, Error, TVariables, TOnMutateResult>({
+    ...mutationOptions,
+    onSuccess: (...args) => {
+      if (invalidateKeys?.length) {
+        for (const key of invalidateKeys) {
+          queryClient.invalidateQueries({ queryKey: key })
+        }
+      }
+      mutationOptions.onSuccess?.(...args)
+    },
+  })
+
+  const apiError = useMemo(
+    () => (mutation.error ? parseApiError(mutation.error) : null),
+    [mutation.error],
+  )
+
+  return {
+    ...mutation,
+    fieldErrors: apiError?.fieldErrors ?? {},
+    apiError,
+    errorMessage: apiError?.message ?? null,
+  }
+}

package/src/templates/frontend/src/shared/hooks/use-api-query.ts.hbs

@@ -0,0 +1,66 @@
+/**
+ * useApiQuery — Enhanced useQuery for API calls
+ *
+ * Wraps TanStack useQuery with:
+ * - Smart retry (skips 401, 403, 404)
+ * - Parsed error messages from DRF responses
+ * - Typed error state
+ *
+ * Usage:
+ *   const { data, errorMessage } = useApiQuery({
+ *     ...blogPostsListOptions({ query: { page: 1 } }),
+ *   })
+ *
+ * Generated by Blacksmith. You own this file — customize as needed.
+ */
+
+import {
+  useQuery,
+  type UseQueryOptions,
+  type UseQueryResult,
+} from '@tanstack/react-query'
+import { parseApiError, type ApiError } from './api-error'
+
+const NON_RETRYABLE_STATUSES = new Set([400, 401, 403, 404, 405, 409, 422])
+
+export type UseApiQueryResult<TData> = UseQueryResult<TData> & {
+  errorMessage: string | null
+  apiError: ApiError | null
+}
+
+export function useApiQuery<
+  TQueryFnData = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends readonly unknown[] = readonly unknown[],
+>(
+  options: UseQueryOptions<TQueryFnData, Error, TData, TQueryKey>,
+): UseApiQueryResult<TData> {
+  const result = useQuery<TQueryFnData, Error, TData, TQueryKey>({
+    retry: (failureCount, error) => {
+      const status = getStatusFromError(error)
+      if (NON_RETRYABLE_STATUSES.has(status)) return false
+      return failureCount < 2
+    },
+    ...options,
+  })
+
+  const apiError = result.error ? parseApiError(result.error) : null
+
+  return {
+    ...result,
+    errorMessage: apiError?.message ?? null,
+    apiError,
+  }
+}
+
+function getStatusFromError(error: unknown): number {
+  if (error && typeof error === 'object') {
+    if ('status' in error && typeof (error as any).status === 'number') {
+      return (error as any).status
+    }
+    if ('response' in error && (error as any).response?.status) {
+      return (error as any).response.status
+    }
+  }
+  return 0
+}

package/src/templates/frontend/src/shared/hooks/use-debounce.ts.hbs

@@ -0,0 +1,10 @@
+/**
+ * useDebounce Hook
+ *
+ * Re-exports useDebounce from @blacksmith-ui/hooks.
+ * Import from here so your app has a single import path.
+ *
+ * Generated by Blacksmith. You own this file — customize as needed.
+ */
+
+export { useDebounce } from '@blacksmith-ui/hooks'