solokit 0.1.1__py3-none-any.whl

solokit/templates/feature_spec.md

@@ -0,0 +1,248 @@
+# Feature: [Feature Name]
+
+<!--
+TEMPLATE INSTRUCTIONS:
+- Replace [Feature Name] with the actual feature name
+- Fill out all sections below with specific details
+- Use concrete examples where possible
+- Check off items in checklists as you complete them
+- Remove these instructions before finalizing the spec
+-->
+
+## Overview
+
+<!-- Provide a 2-3 sentence description of what this feature does and why it's needed -->
+
+Brief description of what this feature does and why it's needed.
+
+**Example:**
+> This feature adds real-time notifications to the dashboard, alerting users when important events occur. It uses WebSocket connections to push updates without requiring page refreshes, improving user experience and reducing server load from polling.
+
+## User Story
+
+<!-- Describe who benefits and what they achieve with this feature -->
+
+As a [type of user], I want [goal] so that [benefit].
+
+**Example:**
+> As a dashboard user, I want to receive real-time notifications when my tasks are updated so that I can respond quickly without constantly refreshing the page.
+
+## Rationale
+
+<!-- Explain the business value, problem being solved, or opportunity being addressed -->
+
+Why is this feature important? What problem does it solve?
+
+**Consider:**
+- What pain point does this address?
+- What business value does it provide?
+- What happens if we don't build this?
+- Are there user requests or metrics supporting this?
+
+## Acceptance Criteria
+
+<!-- Specific, measurable criteria that must be met for this feature to be considered complete -->
+
+- [ ] Users can see notifications in real-time without page refresh
+- [ ] Notifications are displayed in a non-intrusive manner
+- [ ] Users can dismiss individual notifications
+- [ ] Users can view notification history for the past 30 days
+- [ ] System sends notifications for all supported event types
+- [ ] Notifications work across multiple browser tabs
+- [ ] All tests pass including new notification tests
+- [ ] Documentation is updated
+
+## Implementation Details
+
+### Approach
+
+<!-- High-level technical approach and key design decisions -->
+
+**Example:**
+> We'll implement WebSocket connections using Socket.IO for bidirectional communication. The server will emit events when tasks are updated, and the client will listen for these events and update the UI. We'll use a notification queue on the backend to handle high-volume scenarios and ensure delivery.
+
+### LLM/Processing Configuration
+
+<!-- For LLM-based features: Document DSPy signatures, LLM provider, and usage patterns
+     For deterministic features: Describe processing type and algorithms
+     For external API features: Document API integration details
+     If not applicable: State "Not Applicable" -->
+
+**For LLM-based features:**
+
+```markdown
+**Type:** LLM-based (DSPy)
+
+**DSPy Signature:**
+```python
+class ExampleSignature(dspy.Signature):
+    """Description of what this signature does."""
+
+    input_field = dspy.InputField(desc="Description of input")
+    output_field = dspy.OutputField(desc="Description of output")
+```
+
+**LLM Provider:** Google AI Studio (Gemini 2.5 Flash)
+
+**LLM Usage:**
+- Analyzes input data to extract key information
+- Generates structured output based on learned patterns
+- Fallback to rule-based processing if LLM unavailable
+```
+
+**For deterministic/non-LLM features:**
+
+```markdown
+**Type:** Deterministic (No LLM)
+
+**Processing Type:**
+- Parse input data using regex patterns
+- Transform data through validation pipeline
+- Apply business logic rules to generate output
+- Use algorithm X for data aggregation
+```
+
+**For external API integration:**
+
+```markdown
+**Type:** External API Integration (No LLM)
+
+**API Provider:** [Provider name]
+
+**Processing Type:**
+- Make API calls to external service
+- Transform API responses to internal format
+- Handle rate limiting and retries
+- Cache results for performance
+
+**Rate Limits:** [Details if applicable]
+```
+
+**If not applicable:**
+
+```markdown
+Not Applicable - Standard application logic without LLM or special processing requirements.
+```
+
+### Components Affected
+
+<!-- List all files, modules, or systems that will be modified -->
+
+- Frontend: `src/components/NotificationCenter.tsx` (new)
+- Frontend: `src/hooks/useWebSocket.ts` (new)
+- Frontend: `src/services/notificationService.ts` (new)
+- Backend: `src/websocket/notificationHandler.ts` (new)
+- Backend: `src/models/Notification.ts` (new)
+- Database: `notifications` table (new)
+
+### API Changes
+
+<!-- Document all new or modified API endpoints, parameters, and responses -->
+
+**New Endpoints:**
+
+```typescript
+// WebSocket connection endpoint
+ws://api.example.com/notifications
+
+// Events emitted:
+{
+  event: "task.updated",
+  data: {
+    taskId: string,
+    title: string,
+    changes: object,
+    timestamp: Date
+  }
+}
+
+// REST endpoint for notification history
+GET /api/notifications?limit=50&offset=0
+Response: {
+  notifications: Notification[],
+  total: number
+}
+
+// Mark notification as read
+PATCH /api/notifications/:id/read
+Response: {
+  success: boolean
+}
+```
+
+### Database Changes
+
+<!-- Document all schema changes, migrations, and data transformations -->
+
+**New Table:**
+
+```sql
+CREATE TABLE notifications (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id),
+  type VARCHAR(50) NOT NULL,
+  title VARCHAR(255) NOT NULL,
+  message TEXT,
+  data JSONB,
+  read BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT NOW(),
+  INDEX idx_user_created (user_id, created_at DESC)
+);
+```
+
+**Migration:**
+- File: `migrations/2025_10_add_notifications_table.sql`
+- Rollback: Drop table and indexes
+
+## Testing Strategy
+
+<!-- Comprehensive testing approach for this feature -->
+
+### Unit Tests
+- NotificationCenter component rendering and interaction
+- WebSocket connection lifecycle management
+- Notification service message handling
+- Database query functions
+
+### Integration Tests
+- End-to-end WebSocket communication
+- Notification creation and retrieval flow
+- Multi-tab notification synchronization
+- Notification history pagination
+
+### Manual Testing
+- [ ] Test on Chrome, Firefox, Safari
+- [ ] Test with slow network connection
+- [ ] Test with WebSocket connection drops and reconnects
+- [ ] Test notification display with various content lengths
+- [ ] Test concurrent notifications (stress test)
+- [ ] Test notification persistence across page reloads
+
+## Documentation Updates
+
+- [ ] User documentation: How to manage notifications
+- [ ] API documentation: WebSocket events and REST endpoints
+- [ ] README updates: New WebSocket dependencies
+- [ ] Architecture docs: Notification system design
+- [ ] Deployment notes: WebSocket infrastructure requirements
+
+## Dependencies
+
+<!-- List any other work items, external libraries, or infrastructure this depends on -->
+
+- `feature_user_authentication` (must be completed first)
+- `refactor_websocket_infrastructure` (must be completed first)
+- New dependency: `socket.io-client` ^4.5.0
+- Infrastructure: WebSocket support in production load balancer
+
+## Estimated Effort
+
+[Number] sessions
+
+<!--
+Estimation guidelines:
+- Simple feature (CRUD, UI update): 1-2 sessions
+- Medium feature (new API, moderate complexity): 2-4 sessions
+- Complex feature (multiple systems, data migration): 4-8 sessions
+- Very complex feature (major architecture change): 8+ sessions
+-->

solokit/templates/fullstack_nextjs/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/fullstack_nextjs/base/app/api/example/route.ts

@@ -0,0 +1,65 @@
+import { NextRequest, NextResponse } from "next/server";
+import { prisma } from "@/lib/prisma";
+import { createUserSchema } from "@/lib/validations";
+import { z } from "zod";
+
+/**
+ * GET /api/example
+ * Returns a simple greeting message
+ */
+export async function GET() {
+  try {
+    // Example: Fetch users from database
+    const users = await prisma.user.findMany({
+      take: 10,
+      orderBy: { createdAt: "desc" },
+    });
+
+    return NextResponse.json({
+      message: "Hello from Next.js API!",
+      users,
+    });
+  } catch (error) {
+    console.error("Error fetching users:", error);
+    return NextResponse.json(
+      { error: "Failed to fetch users" },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * POST /api/example
+ * Creates a new user
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+
+    // Validate request body
+    const validatedData = createUserSchema.parse(body);
+
+    // Create user in database
+    const user = await prisma.user.create({
+      data: {
+        name: validatedData.name,
+        email: validatedData.email,
+      },
+    });
+
+    return NextResponse.json(user, { status: 201 });
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: "Validation failed", details: error.issues },
+        { status: 400 }
+      );
+    }
+
+    console.error("Error creating user:", error);
+    return NextResponse.json(
+      { error: "Failed to create user" },
+      { status: 500 }
+    );
+  }
+}

solokit/templates/fullstack_nextjs/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/fullstack_nextjs/base/app/layout.tsx

@@ -0,0 +1,20 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Full-Stack Next.js App",
+  description: "A simple full-stack Next.js application with Prisma and Zod",
+  icons: [{ rel: "icon", url: "/favicon.ico" }],
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

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

@@ -0,0 +1,32 @@
+import Link from "next/link";
+import ExampleComponent from "@/components/example-component";
+
+export default function Home() {
+  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]">
+          Full-Stack <span className="text-[hsl(280,100%,70%)]">Next.js</span>
+        </h1>
+        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 md:gap-8">
+          <Link
+            href="/api/example"
+            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">API Routes →</h3>
+            <div className="text-lg">
+              Check out the example API route at /api/example
+            </div>
+          </Link>
+          <div className="flex max-w-xs flex-col gap-4 rounded-xl bg-white/10 p-4">
+            <h3 className="text-2xl font-bold">Database →</h3>
+            <div className="text-lg">
+              Prisma ORM with PostgreSQL for type-safe database queries
+            </div>
+          </div>
+        </div>
+        <ExampleComponent />
+      </div>
+    </main>
+  );
+}

solokit/templates/fullstack_nextjs/base/components/example-component.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { useState } from "react";
+
+export default function ExampleComponent() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <div className="flex flex-col items-center gap-4 rounded-xl bg-white/10 p-6">
+      <h3 className="text-2xl font-bold">Client Component Example</h3>
+      <p className="text-lg">Count: {count}</p>
+      <button
+        onClick={() => setCount(count + 1)}
+        className="rounded-lg bg-white/20 px-6 py-2 font-semibold transition hover:bg-white/30"
+      >
+        Increment
+      </button>
+    </div>
+  );
+}

solokit/templates/fullstack_nextjs/base/lib/prisma.ts

@@ -0,0 +1,17 @@
+import { PrismaClient } from "@prisma/client";
+
+const createPrismaClient = () =>
+  new PrismaClient({
+    log:
+      process.env.NODE_ENV === "development"
+        ? ["query", "error", "warn"]
+        : ["error"],
+  });
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: ReturnType<typeof createPrismaClient> | undefined;
+};
+
+export const prisma = globalForPrisma.prisma ?? createPrismaClient();
+
+if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

solokit/templates/fullstack_nextjs/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/fullstack_nextjs/base/lib/validations.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+/**
+ * Validation schema for creating a new user
+ */
+export const createUserSchema = z.object({
+  name: z.string().min(1, "Name is required").max(100),
+  email: z.string().email("Invalid email address"),
+});
+
+/**
+ * Validation schema for updating a user
+ */
+export const updateUserSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  email: z.string().email().optional(),
+});
+
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+export type UpdateUserInput = z.infer<typeof updateUserSchema>;

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

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

solokit/templates/fullstack_nextjs/base/package.json.template

@@ -0,0 +1,32 @@
+{
+  "name": "{project_name}",
+  "version": "0.1.0",
+  "description": "{project_description}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "16.0.1",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "prisma": "6.19.0",
+    "@prisma/client": "6.19.0",
+    "zod": "4.1.12",
+    "tailwindcss": "4.1.17",
+    "@tailwindcss/postcss": "4.1.17",
+    "clsx": "2.1.1",
+    "tailwind-merge": "3.3.1"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/node": "20.19.24",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2"
+  }
+}

solokit/templates/fullstack_nextjs/base/postcss.config.mjs

@@ -0,0 +1,8 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;

solokit/templates/fullstack_nextjs/base/prisma/schema.prisma

@@ -0,0 +1,21 @@
+// This is your Prisma schema file,
+// learn more about it in the docs: https://pris.ly/d/prisma-schema
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        Int      @id @default(autoincrement())
+  name      String
+  email     String   @unique
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([email])
+}

solokit/templates/fullstack_nextjs/base/tailwind.config.ts

@@ -0,0 +1,19 @@
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+  content: [
+    "./app/**/*.{js,ts,jsx,tsx,mdx}",
+    "./components/**/*.{js,ts,jsx,tsx,mdx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        background: "var(--background)",
+        foreground: "var(--foreground)",
+      },
+    },
+  },
+  plugins: [],
+};
+
+export default config;

solokit/templates/fullstack_nextjs/base/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

solokit/templates/fullstack_nextjs/docker/Dockerfile

@@ -0,0 +1,60 @@
+# syntax=docker/dockerfile:1
+
+# Base image
+FROM node:20-alpine AS base
+
+# Install dependencies only when needed
+FROM base AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+# Install dependencies based on the preferred package manager
+COPY package.json package-lock.json* ./
+RUN npm ci
+
+# Rebuild the source code only when needed
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Generate Prisma Client
+RUN npx prisma generate
+
+# Next.js collects completely anonymous telemetry data about general usage.
+# Learn more here: https://nextjs.org/telemetry
+# Uncomment the following line in case you want to disable telemetry during the build.
+# ENV NEXT_TELEMETRY_DISABLED 1
+
+RUN npm run build
+
+# Production image, copy all the files and run next
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV production
+# Uncomment the following line in case you want to disable telemetry during runtime.
+# ENV NEXT_TELEMETRY_DISABLED 1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+# Copy necessary files
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/package.json ./package.json
+
+# Automatically leverage output traces to reduce image size
+# https://nextjs.org/docs/advanced-features/output-file-tracing
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+
+ENV PORT 3000
+ENV HOSTNAME "0.0.0.0"
+
+# server.js is created by next build from the standalone output
+# https://nextjs.org/docs/pages/api-reference/next-config-js/output
+CMD ["node", "server.js"]