solokit 0.1.1__py3-none-any.whl

solokit/templates/ml_ai_fastapi/tier-4-production/src/middleware/logging.py

@@ -0,0 +1,79 @@
+"""
+Request/Response logging middleware
+"""
+
+import time
+from typing import Callable
+
+from fastapi import Request, Response  # type: ignore[import-not-found]
+from src.core.logging import logger  # type: ignore[import-not-found]
+from starlette.middleware.base import BaseHTTPMiddleware  # type: ignore[import-not-found]
+
+
+class LoggingMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware to log all HTTP requests and responses.
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """
+        Process request and log details.
+
+        Args:
+            request: FastAPI request
+            call_next: Next middleware/route handler
+
+        Returns:
+            Response: FastAPI response
+        """
+        # Start timer
+        start_time = time.time()
+
+        # Extract request details
+        method = request.method
+        path = request.url.path
+        client_host = request.client.host if request.client else "unknown"
+
+        # Log incoming request
+        logger.info(
+            "request_started",
+            method=method,
+            path=path,
+            client=client_host,
+        )
+
+        # Process request
+        try:
+            response = await call_next(request)
+
+            # Calculate duration
+            duration = time.time() - start_time
+
+            # Log successful response
+            logger.info(
+                "request_completed",
+                method=method,
+                path=path,
+                status_code=response.status_code,
+                duration=f"{duration:.3f}s",
+            )
+
+            # Add custom headers
+            response.headers["X-Process-Time"] = str(duration)
+
+            return response
+
+        except Exception as e:
+            # Calculate duration
+            duration = time.time() - start_time
+
+            # Log error
+            logger.error(
+                "request_failed",
+                method=method,
+                path=path,
+                duration=f"{duration:.3f}s",
+                error=str(e),
+                exc_info=True,
+            )
+            raise

solokit/templates/ml_ai_fastapi/tier-4-production/src/middleware/tracing.py

@@ -0,0 +1,60 @@
+"""
+OpenTelemetry tracing middleware
+"""
+
+from typing import Any, Callable
+
+from fastapi import Request, Response  # type: ignore[import-not-found]
+from opentelemetry import trace  # type: ignore[import-not-found]
+from opentelemetry.instrumentation.fastapi import (
+    FastAPIInstrumentor,  # type: ignore[import-not-found]
+)
+from src.core.config import settings  # type: ignore[import-not-found]
+from starlette.middleware.base import BaseHTTPMiddleware  # type: ignore[import-not-found]
+
+
+class TracingMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware to add distributed tracing with OpenTelemetry.
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """
+        Add tracing context to request.
+
+        Args:
+            request: FastAPI request
+            call_next: Next middleware/route handler
+
+        Returns:
+            Response: FastAPI response
+        """
+        tracer = trace.get_tracer(__name__)
+
+        with tracer.start_as_current_span(
+            f"{request.method} {request.url.path}",
+            attributes={
+                "http.method": request.method,
+                "http.url": str(request.url),
+                "http.client": request.client.host if request.client else "unknown",
+            },
+        ) as span:
+            response = await call_next(request)
+
+            # Add response attributes to span
+            span.set_attribute("http.status_code", response.status_code)
+
+            return response
+
+
+def configure_tracing(app: Any) -> None:
+    """
+    Configure OpenTelemetry tracing for FastAPI application.
+
+    Args:
+        app: FastAPI application instance
+    """
+    # Only configure tracing in production
+    if settings.ENVIRONMENT != "development":
+        # Instrument FastAPI
+        FastAPIInstrumentor.instrument_app(app)

solokit/templates/refactor_spec.md

@@ -0,0 +1,287 @@
+# Refactor: [Refactor Title]
+
+<!--
+TEMPLATE INSTRUCTIONS:
+- Replace [Refactor Title] with a concise description of what's being refactored
+- Include before/after code examples to show the improvement
+- Clearly document why this refactor is valuable
+- Be explicit about scope to avoid scope creep
+- Remove these instructions before finalizing the spec
+-->
+
+## Overview
+
+<!-- What is being refactored and why is it important? -->
+
+What is being refactored and why?
+
+**Example:**
+> Refactor the UserService class to use dependency injection instead of direct instantiation of dependencies. This will improve testability, reduce coupling, and make the codebase more maintainable as we scale.
+
+## Current State
+
+<!-- Description of the current implementation with code examples -->
+
+**Example:**
+> The `UserService` class directly instantiates its dependencies (DatabaseClient, EmailService, CacheManager), making it difficult to test and tightly coupled to specific implementations.
+
+**Current Code:**
+```typescript
+// src/services/UserService.ts (BEFORE)
+class UserService {
+  private db: DatabaseClient;
+  private email: EmailService;
+  private cache: CacheManager;
+
+  constructor() {
+    // Hard-coded dependencies - difficult to test!
+    this.db = new DatabaseClient(config.database);
+    this.email = new EmailService(config.email);
+    this.cache = new CacheManager(config.redis);
+  }
+
+  async createUser(data: UserData): Promise<User> {
+    const user = await this.db.insert('users', data);
+    await this.email.sendWelcomeEmail(user.email);
+    await this.cache.set(`user:${user.id}`, user);
+    return user;
+  }
+}
+```
+
+## Problems with Current Approach
+
+<!-- Specific issues with the current implementation -->
+
+- **Tight Coupling:** Service is tightly coupled to specific implementations of DatabaseClient, EmailService, and CacheManager
+- **Difficult to Test:** Cannot mock dependencies in unit tests without complex workarounds
+- **Configuration Hardcoding:** Config is accessed directly, making it hard to override for different environments
+- **Single Responsibility Violation:** Constructor is responsible for both dependency creation and initialization
+- **No Interface Contracts:** Dependencies don't implement interfaces, making swapping implementations impossible
+
+**Test Difficulty Example:**
+```typescript
+// Current test - requires real dependencies!
+describe('UserService', () => {
+  it('creates a user', async () => {
+    const service = new UserService(); // Can't inject mocks!
+    // Test requires real database, email server, Redis...
+  });
+});
+```
+
+## Proposed Refactor
+
+### New Approach
+
+<!-- Description of the refactored implementation with code examples -->
+
+**Example:**
+> Introduce dependency injection using constructor injection with interface-based dependencies. Create interfaces for each dependency and inject them through the constructor.
+
+**Refactored Code:**
+```typescript
+// src/interfaces/IDatabase.ts (NEW)
+interface IDatabase {
+  insert(table: string, data: any): Promise<any>;
+  find(table: string, id: string): Promise<any>;
+}
+
+// src/interfaces/IEmailService.ts (NEW)
+interface IEmailService {
+  sendWelcomeEmail(email: string): Promise<void>;
+}
+
+// src/interfaces/ICacheManager.ts (NEW)
+interface ICacheManager {
+  set(key: string, value: any): Promise<void>;
+  get(key: string): Promise<any>;
+}
+
+// src/services/UserService.ts (AFTER)
+class UserService {
+  constructor(
+    private db: IDatabase,
+    private email: IEmailService,
+    private cache: ICacheManager
+  ) {
+    // Dependencies injected - easy to test!
+  }
+
+  async createUser(data: UserData): Promise<User> {
+    const user = await this.db.insert('users', data);
+    await this.email.sendWelcomeEmail(user.email);
+    await this.cache.set(`user:${user.id}`, user);
+    return user;
+  }
+}
+
+// src/container.ts (NEW) - Dependency injection container
+export const container = {
+  userService: new UserService(
+    new DatabaseClient(config.database),
+    new EmailService(config.email),
+    new CacheManager(config.redis)
+  )
+};
+```
+
+### Benefits
+
+<!-- Concrete benefits of the refactored approach -->
+
+- **Testability:** Can easily inject mocks/stubs in tests
+- **Loose Coupling:** Service depends on interfaces, not concrete implementations
+- **Flexibility:** Easy to swap implementations (e.g., use different cache provider)
+- **Maintainability:** Clear dependency contracts via interfaces
+- **Single Responsibility:** Constructor only receives dependencies, doesn't create them
+
+**Testing Improvement:**
+```typescript
+// New test - easy to mock dependencies!
+describe('UserService', () => {
+  it('creates a user', async () => {
+    const mockDb = { insert: jest.fn().mockResolvedValue({ id: '123' }) };
+    const mockEmail = { sendWelcomeEmail: jest.fn() };
+    const mockCache = { set: jest.fn() };
+
+    const service = new UserService(mockDb, mockEmail, mockCache);
+    await service.createUser({ name: 'Test' });
+
+    expect(mockDb.insert).toHaveBeenCalled();
+    expect(mockEmail.sendWelcomeEmail).toHaveBeenCalled();
+  });
+});
+```
+
+### Trade-offs
+
+<!-- Any downsides or considerations -->
+
+- **Slightly More Boilerplate:** Need to define interfaces for dependencies
+- **Container Setup:** Need to set up dependency injection container
+- **Learning Curve:** Team needs to understand DI pattern
+- **Migration Effort:** Existing code needs to be updated to use new pattern
+
+## Implementation Plan
+
+<!-- Step-by-step plan for implementing the refactor -->
+
+1. **Phase 1: Create Interfaces** (0.5 sessions)
+   - Define `IDatabase`, `IEmailService`, `ICacheManager` interfaces
+   - Ensure existing implementations satisfy interfaces
+
+2. **Phase 2: Refactor UserService** (0.5 sessions)
+   - Update `UserService` constructor to accept injected dependencies
+   - Update all methods to use injected dependencies
+
+3. **Phase 3: Create DI Container** (0.5 sessions)
+   - Create `src/container.ts` with dependency wiring
+   - Update application entry point to use container
+
+4. **Phase 4: Update Tests** (1 session)
+   - Refactor all UserService tests to use mocks
+   - Add new tests for edge cases now easy to test
+
+5. **Phase 5: Update Callers** (0.5 sessions)
+   - Update all code that instantiates UserService
+   - Ensure all use container.userService instead
+
+## Scope
+
+### In Scope
+
+<!-- What will be refactored in this work item -->
+
+- UserService class refactoring
+- Interface definitions for Database, EmailService, CacheManager
+- Basic dependency injection container
+- UserService test refactoring
+- Documentation updates
+
+### Out of Scope
+
+<!-- What will NOT be refactored -->
+
+- Refactoring other services (future work)
+- Advanced DI container features (auto-wiring, decorators)
+- Refactoring DatabaseClient, EmailService, CacheManager internals
+- Performance optimization (separate work item)
+
+## Risk Assessment
+
+<!-- Identify and mitigate risks -->
+
+- **Risk Level:** Medium
+- **Risks:**
+  - Breaking existing functionality if dependency wiring is incorrect
+  - Tests might miss integration issues if mocking is too aggressive
+  - Performance regression if DI container adds overhead
+- **Mitigation:**
+  - Comprehensive test coverage before and after refactor
+  - Integration tests to verify end-to-end functionality
+  - Performance benchmarks to detect regressions
+  - Gradual rollout with feature flag
+  - Code review focusing on dependency correctness
+
+## Acceptance Criteria
+
+<!-- Define specific, measurable criteria for considering this refactor complete -->
+<!-- Minimum 3 items required for spec validation -->
+
+- [ ] All code in scope has been refactored according to the proposed approach
+- [ ] All existing functionality preserved (no breaking changes)
+- [ ] All existing tests pass without modification
+- [ ] Code quality metrics improved (complexity, coupling, testability)
+- [ ] No performance regressions detected
+- [ ] New tests added for previously untestable scenarios
+- [ ] Code review completed and approved
+- [ ] Documentation updated to reflect new structure
+
+**Example criteria for a specific refactor:**
+- [ ] UserService uses dependency injection with interface-based contracts
+- [ ] All UserService dependencies injected through constructor
+- [ ] Unit test code reduced by >30% due to improved mockability
+- [ ] Cyclomatic complexity reduced from 12 to 6
+- [ ] 100% test coverage maintained or improved
+
+## Testing Strategy
+
+<!-- How to verify the refactor doesn't break anything -->
+
+### Automated Tests
+- [ ] All existing UserService tests pass with new implementation
+- [ ] New tests added for previously untestable scenarios
+- [ ] Integration tests verify end-to-end functionality
+- [ ] Performance tests show no regression (< 5% latency increase)
+
+### Manual Testing
+- [ ] User creation flow works end-to-end
+- [ ] Error handling works correctly
+- [ ] Email notifications are sent
+- [ ] Cache is populated correctly
+
+### Code Quality Metrics
+- [ ] Cyclomatic complexity reduced by at least 20%
+- [ ] Test coverage increased from 65% to 85%+
+- [ ] No new linting errors introduced
+- [ ] Code duplication reduced
+
+## Dependencies
+
+<!-- List any dependencies on other work -->
+
+- None (this is a self-contained refactor)
+
+## Estimated Effort
+
+3 sessions
+
+<!--
+Breakdown:
+- Phase 1: 0.5 sessions
+- Phase 2: 0.5 sessions
+- Phase 3: 0.5 sessions
+- Phase 4: 1 session
+- Phase 5: 0.5 sessions
+-->

solokit/templates/saas_t3/base/.gitignore

@@ -0,0 +1,36 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

solokit/templates/saas_t3/base/app/api/trpc/[trpc]/route.ts

@@ -0,0 +1,33 @@
+import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
+import { type NextRequest } from "next/server";
+
+import { appRouter } from "@/server/api/root";
+import { createTRPCContext } from "@/server/api/trpc";
+
+/**
+ * This wraps the `createTRPCContext` helper and provides the required context for the tRPC API when
+ * handling a HTTP request (e.g. when you make requests from Client Components).
+ */
+const createContext = async (req: NextRequest) => {
+  return createTRPCContext({
+    headers: req.headers,
+  });
+};
+
+const handler = (req: NextRequest) =>
+  fetchRequestHandler({
+    endpoint: "/api/trpc",
+    req,
+    router: appRouter,
+    createContext: () => createContext(req),
+    onError:
+      process.env.NODE_ENV === "development"
+        ? ({ path, error }) => {
+            console.error(
+              `❌ tRPC failed on ${path ?? "<no-path>"}: ${error.message}`
+            );
+          }
+        : undefined,
+  });
+
+export { handler as GET, handler as POST };

solokit/templates/saas_t3/base/app/globals.css

@@ -0,0 +1,27 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+body {
+  color: var(--foreground);
+  background: var(--background);
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+@layer utilities {
+  .text-balance {
+    text-wrap: balance;
+  }
+}

solokit/templates/saas_t3/base/app/layout.tsx

@@ -0,0 +1,23 @@
+import type { Metadata } from "next";
+import { TRPCReactProvider } from "@/lib/api";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Create T3 App",
+  description: "Generated by create-t3-app",
+  icons: [{ rel: "icon", url: "/favicon.ico" }],
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body>
+        <TRPCReactProvider>{children}</TRPCReactProvider>
+      </body>
+    </html>
+  );
+}

solokit/templates/saas_t3/base/app/page.tsx

@@ -0,0 +1,31 @@
+"use client";
+
+import { api } from "@/lib/api";
+
+export default function Home() {
+  const hello = api.example.hello.useQuery({ text: "from tRPC" });
+
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center bg-gradient-to-b from-[#2e026d] to-[#15162c] text-white">
+      <div className="container flex flex-col items-center justify-center gap-12 px-4 py-16">
+        <h1 className="text-5xl font-extrabold tracking-tight sm:text-[5rem]">
+          Create <span className="text-[hsl(280,100%,70%)]">T3</span> App
+        </h1>
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 md:gap-8">
+          <div className="flex max-w-xs flex-col gap-4 rounded-xl bg-white/10 p-4 hover:bg-white/20">
+            <h3 className="text-2xl font-bold">First Steps →</h3>
+            <div className="text-lg">
+              {hello.data ? hello.data.greeting : "Loading tRPC query..."}
+            </div>
+          </div>
+          <div className="flex max-w-xs flex-col gap-4 rounded-xl bg-white/10 p-4 hover:bg-white/20">
+            <h3 className="text-2xl font-bold">Documentation →</h3>
+            <div className="text-lg">
+              Learn more about the T3 Stack and its components.
+            </div>
+          </div>
+        </div>
+      </div>
+    </main>
+  );
+}

solokit/templates/saas_t3/base/lib/api.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { httpBatchLink, loggerLink } from "@trpc/client";
+import { createTRPCReact } from "@trpc/react-query";
+import { inferRouterInputs, inferRouterOutputs } from "@trpc/server";
+import { useState } from "react";
+import superjson from "superjson";
+
+import type { AppRouter } from "@/server/api/root";
+
+const createQueryClient = () => new QueryClient();
+
+let clientQueryClientSingleton: QueryClient | undefined = undefined;
+const getQueryClient = () => {
+  if (typeof window === "undefined") {
+    // Server: always make a new query client
+    return createQueryClient();
+  }
+  // Browser: use singleton pattern to keep the same query client
+  return (clientQueryClientSingleton ??= createQueryClient());
+};
+
+export const api = createTRPCReact<AppRouter>();
+
+/**
+ * Inference helper for inputs.
+ *
+ * @example type HelloInput = RouterInputs['example']['hello']
+ */
+export type RouterInputs = inferRouterInputs<AppRouter>;
+
+/**
+ * Inference helper for outputs.
+ *
+ * @example type HelloOutput = RouterOutputs['example']['hello']
+ */
+export type RouterOutputs = inferRouterOutputs<AppRouter>;
+
+export function TRPCReactProvider(props: { children: React.ReactNode }) {
+  const queryClient = getQueryClient();
+
+  const [trpcClient] = useState(() =>
+    api.createClient({
+      links: [
+        loggerLink({
+          enabled: (op) =>
+            process.env.NODE_ENV === "development" ||
+            (op.direction === "down" && op.result instanceof Error),
+        }),
+        httpBatchLink({
+          transformer: superjson,
+          url: getBaseUrl() + "/api/trpc",
+          headers: () => {
+            const headers = new Headers();
+            headers.set("x-trpc-source", "nextjs-react");
+            return headers;
+          },
+        }),
+      ],
+    })
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <api.Provider client={trpcClient} queryClient={queryClient}>
+        {props.children}
+      </api.Provider>
+    </QueryClientProvider>
+  );
+}
+
+function getBaseUrl() {
+  if (typeof window !== "undefined") return window.location.origin;
+  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`;
+  return `http://localhost:${process.env.PORT ?? 3000}`;
+}

solokit/templates/saas_t3/base/lib/utils.ts

@@ -0,0 +1,13 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Utility function to merge Tailwind CSS classes
+ *
+ * @example
+ * cn("px-2 py-1", "bg-blue-500") // "px-2 py-1 bg-blue-500"
+ * cn("px-2", condition && "py-1") // "px-2 py-1" or "px-2"
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

solokit/templates/saas_t3/base/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;