@tekyzinc/gsd-t 2.45.11 → 2.50.10

package/templates/stacks/graphql.md

@@ -0,0 +1,216 @@
+# GraphQL Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Schema Design
+
+```
+MANDATORY:
+  ├── Schema-first design — define the schema, then implement resolvers
+  ├── Use PascalCase for types: User, OrderItem
+  ├── Use camelCase for fields: firstName, createdAt
+  ├── Use UPPER_SNAKE_CASE for enum values: ACTIVE, PENDING_REVIEW
+  ├── Input types for mutations: CreateUserInput, UpdateOrderInput
+  ├── Every mutation returns the affected type (not just Boolean)
+  └── Add descriptions to all types and fields — they power documentation
+```
+
+**GOOD**
+```graphql
+"""A registered user in the system."""
+type User {
+  id: ID!
+  """User's display name."""
+  displayName: String!
+  email: String!
+  role: UserRole!
+  orders(first: Int = 20, after: String): OrderConnection!
+  createdAt: DateTime!
+}
+
+enum UserRole {
+  ADMIN
+  MEMBER
+  VIEWER
+}
+
+input CreateUserInput {
+  displayName: String!
+  email: String!
+  role: UserRole = MEMBER
+}
+```
+
+---
+
+## 2. Query Design
+
+```
+MANDATORY:
+  ├── Singular for single resource: user(id: ID!): User
+  ├── Plural for collections: users(first: Int, after: String, filter: UserFilter): UserConnection!
+  ├── Use connection pattern (Relay) for paginated lists
+  ├── Accept filter input types — not individual filter args
+  ├── NEVER return unbounded lists — always require pagination args
+  └── Nullable return for single lookups (user may not exist)
+```
+
+**GOOD**
+```graphql
+type Query {
+  user(id: ID!): User
+  users(first: Int = 20, after: String, filter: UserFilter): UserConnection!
+}
+
+input UserFilter {
+  role: UserRole
+  isActive: Boolean
+  search: String
+}
+
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type UserEdge {
+  node: User!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  endCursor: String
+}
+```
+
+---
+
+## 3. Mutation Design
+
+```
+MANDATORY:
+  ├── Verb-first naming: createUser, updateOrder, deleteComment
+  ├── Accept a single input argument: createUser(input: CreateUserInput!): User!
+  ├── Return the mutated object — not Boolean or generic status
+  ├── Use union types for error handling (preferred) or throw errors
+  ├── Validate inputs in resolvers — schema types are not sufficient
+  └── Mutations must be idempotent where possible
+```
+
+**GOOD**
+```graphql
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): User!
+  deleteUser(id: ID!): DeleteUserPayload!
+}
+
+type CreateUserPayload {
+  user: User
+  errors: [ValidationError!]
+}
+
+type ValidationError {
+  field: String!
+  message: String!
+}
+```
+
+---
+
+## 4. Resolver Patterns
+
+```
+MANDATORY:
+  ├── Thin resolvers — delegate to service/data layer, don't put business logic in resolvers
+  ├── Use DataLoader for N+1 prevention — batch and cache database lookups
+  ├── Auth checks in resolvers or middleware — not in the service layer
+  ├── Return null for not-found, throw for unauthorized/forbidden
+  └── Log errors with context (query name, variables, user ID)
+```
+
+**GOOD**
+```typescript
+const resolvers = {
+  Query: {
+    user: async (_, { id }, { dataSources, user }) => {
+      if (!user) throw new AuthenticationError('Must be logged in');
+      return dataSources.userService.getById(id);
+    },
+  },
+  User: {
+    orders: (parent, args, { dataSources }) =>
+      dataSources.orderLoader.load({ userId: parent.id, ...args }),
+  },
+};
+```
+
+---
+
+## 5. N+1 Prevention — DataLoader
+
+```
+MANDATORY:
+  ├── Use DataLoader for any field that resolves per-item in a list
+  ├── Create loaders per request (new instance in context factory)
+  ├── Batch function receives array of keys, returns array of results in same order
+  └── Cache is request-scoped — not shared between requests
+```
+
+**GOOD**
+```typescript
+const userLoader = new DataLoader<string, User>(async (ids) => {
+  const users = await db.query('SELECT * FROM users WHERE id = ANY($1)', [ids]);
+  const userMap = new Map(users.map(u => [u.id, u]));
+  return ids.map(id => userMap.get(id) ?? new Error(`User ${id} not found`));
+});
+```
+
+---
+
+## 6. Client-Side Patterns
+
+```
+MANDATORY:
+  ├── Co-locate queries with components — query file next to the component
+  ├── Use fragments for shared field selections
+  ├── Name all operations: query GetUser, mutation CreateOrder
+  ├── Use generated types (graphql-codegen) — NEVER manually type query results
+  ├── Handle loading, error, and empty states for every query
+  └── Cache update after mutations: refetch or update cache directly
+```
+
+---
+
+## 7. Anti-Patterns
+
+```
+NEVER:
+  ├── Unbounded list queries without pagination
+  ├── Business logic in resolvers — delegate to services
+  ├── N+1 queries — use DataLoader
+  ├── Anonymous operations (unnamed queries/mutations)
+  ├── Deeply nested queries without depth limiting
+  ├── Returning Boolean from mutations — return the affected type
+  ├── Over-fetching: requesting all fields when you need two
+  └── Manually typing query results — use codegen
+```
+
+---
+
+## GraphQL Verification Checklist
+
+- [ ] Schema-first with descriptions on all types/fields
+- [ ] Connection pattern for paginated lists
+- [ ] All mutations return affected type (not Boolean)
+- [ ] DataLoader used for N+1 prevention
+- [ ] Input validation in resolvers
+- [ ] Auth checks in resolvers or middleware
+- [ ] Operations named (query GetUser, not anonymous)
+- [ ] Generated types via codegen
+- [ ] Loading, error, empty states handled client-side
+- [ ] Query depth limiting configured

package/templates/stacks/neo4j.md

@@ -0,0 +1,218 @@
+# Neo4j Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Data Modeling
+
+```
+MANDATORY:
+  ├── Nodes represent entities (nouns): (:User), (:Product), (:Order)
+  ├── Relationships represent verbs: -[:PURCHASED]->. -[:FOLLOWS]->
+  ├── Node labels: PascalCase singular (User, BusinessType — not users)
+  ├── Relationship types: UPPER_SNAKE_CASE (PURCHASED, WORKS_AT, BELONGS_TO)
+  ├── Properties: camelCase (firstName, createdAt)
+  ├── Store properties on the node or relationship that "owns" them
+  ├── Relationships ALWAYS have a direction — even if queried bidirectionally
+  └── NEVER use relationships as nodes (reify only when the relationship needs its own relationships)
+```
+
+**GOOD**
+```cypher
+(:User {id: "u-123", name: "Jane", email: "jane@example.com"})
+  -[:PURCHASED {purchasedAt: datetime(), amount: 29.99}]->
+(:Product {id: "p-456", name: "Widget", category: "Tools"})
+```
+
+---
+
+## 2. Cypher Query Patterns
+
+```
+MANDATORY:
+  ├── Use parameterized queries — NEVER string concatenation
+  ├── Use MERGE for upserts — CREATE for guaranteed-new, MATCH for existing
+  ├── Always LIMIT results on user-facing queries
+  ├── Use OPTIONAL MATCH when the relationship may not exist
+  ├── Use WITH to chain query stages — improves readability and performance
+  ├── Prefer pattern comprehension over COLLECT + UNWIND for subqueries
+  └── Always specify relationship direction in MATCH patterns
+```
+
+**BAD**
+```cypher
+MATCH (u:User) WHERE u.name = '${name}' RETURN u  // injection risk!
+MATCH (u:User)--(p:Product) RETURN u, p            // no direction, no limit
+```
+
+**GOOD**
+```cypher
+MATCH (u:User {id: $userId})-[:PURCHASED]->(p:Product)
+RETURN u.name, p.name, p.category
+ORDER BY p.name
+LIMIT 50
+```
+
+---
+
+## 3. Indexing and Constraints
+
+```
+MANDATORY:
+  ├── Unique constraint on all ID properties: CREATE CONSTRAINT FOR (u:User) REQUIRE u.id IS UNIQUE
+  ├── Index properties used in WHERE and MATCH lookups
+  ├── Composite indexes for multi-property lookups
+  ├── Full-text indexes for search fields (name, description)
+  ├── Use EXPLAIN and PROFILE to verify query plans use indexes
+  └── NEVER rely on full node scans for lookups
+```
+
+**GOOD**
+```cypher
+// Unique constraint (also creates an index)
+CREATE CONSTRAINT user_id_unique FOR (u:User) REQUIRE u.id IS UNIQUE;
+
+// Property index for common lookups
+CREATE INDEX user_email_idx FOR (u:User) ON (u.email);
+
+// Composite index
+CREATE INDEX order_status_date FOR (o:Order) ON (o.status, o.createdAt);
+
+// Full-text index for search
+CREATE FULLTEXT INDEX user_search FOR (u:User) ON EACH [u.name, u.email];
+```
+
+---
+
+## 4. Transaction Management
+
+```
+MANDATORY:
+  ├── Use explicit transactions for multi-statement operations
+  ├── Keep transactions short — don't hold locks while doing external I/O
+  ├── Read transactions for queries: session.executeRead()
+  ├── Write transactions for mutations: session.executeWrite()
+  ├── Handle transient errors with retry (the driver retries automatically in managed transactions)
+  └── Always close sessions after use
+```
+
+**GOOD**
+```typescript
+const session = driver.session();
+try {
+  const result = await session.executeRead(async (tx) => {
+    const res = await tx.run(
+      'MATCH (u:User {id: $userId})-[:PURCHASED]->(p:Product) RETURN p',
+      { userId }
+    );
+    return res.records.map(r => r.get('p').properties);
+  });
+  return result;
+} finally {
+  await session.close();
+}
+```
+
+---
+
+## 5. Driver Configuration
+
+```
+MANDATORY:
+  ├── Create driver once at startup — reuse across requests
+  ├── Set maxConnectionPoolSize based on workload (default 100 is usually fine)
+  ├── Set connectionAcquisitionTimeout (default 60s — lower for web apps)
+  ├── Use bolt:// for direct, neo4j:// for routing (cluster)
+  ├── Verify connectivity at startup: driver.verifyConnectivity()
+  └── Close driver on application shutdown: driver.close()
+```
+
+**GOOD**
+```typescript
+import neo4j from 'neo4j-driver';
+
+const driver = neo4j.driver(
+  process.env.NEO4J_URI!,
+  neo4j.auth.basic(process.env.NEO4J_USER!, process.env.NEO4J_PASSWORD!),
+  {
+    maxConnectionPoolSize: 50,
+    connectionAcquisitionTimeout: 10000,
+  }
+);
+
+await driver.verifyConnectivity();
+
+// On shutdown:
+process.on('SIGTERM', () => driver.close());
+```
+
+---
+
+## 6. Performance
+
+```
+MANDATORY:
+  ├── PROFILE queries during development to check plan and db hits
+  ├── Use indexes — full node scans are O(n) and kill performance
+  ├── Avoid variable-length paths without upper bound: -[:FOLLOWS*1..5]-> not -[:FOLLOWS*]->
+  ├── Use LIMIT early in the query — not just at the end
+  ├── Batch large writes (1000-5000 nodes per transaction)
+  └── Use APOC for batch operations when available
+```
+
+**BAD** — unbounded variable-length path:
+```cypher
+MATCH (u:User)-[:FOLLOWS*]->(f:User) RETURN f  // scans entire graph!
+```
+
+**GOOD**
+```cypher
+MATCH (u:User {id: $userId})-[:FOLLOWS*1..3]->(f:User)
+RETURN DISTINCT f.id, f.name
+LIMIT 100
+```
+
+---
+
+## 7. APOC Patterns
+
+```
+WHEN APOC IS AVAILABLE:
+  ├── apoc.periodic.iterate for large batch operations
+  ├── apoc.merge.node for conditional upserts with labels
+  ├── apoc.path.expandConfig for complex traversals with filters
+  ├── apoc.export.json for data dumps
+  └── Check APOC version compatibility with your Neo4j version
+```
+
+---
+
+## 8. Anti-Patterns
+
+```
+NEVER:
+  ├── String concatenation in Cypher — use parameters ($param)
+  ├── Unbounded queries without LIMIT
+  ├── Variable-length paths without upper bound (-[:REL*]->)
+  ├── Missing indexes on lookup properties
+  ├── Creating a new driver per request — reuse the driver
+  ├── Storing large blobs in node properties — use external storage
+  ├── Dense connected nodes (supernode > 100K relationships) without optimization
+  └── Using nodes where relationships should be used (and vice versa)
+```
+
+---
+
+## Neo4j Verification Checklist
+
+- [ ] Parameterized queries only — no string concatenation
+- [ ] Unique constraints on all ID properties
+- [ ] Indexes on all WHERE/MATCH lookup properties
+- [ ] All queries have LIMIT
+- [ ] Variable-length paths have upper bounds
+- [ ] Explicit read/write transactions
+- [ ] Driver created once and reused
+- [ ] Sessions closed after use
+- [ ] PROFILE run on complex queries
+- [ ] Node labels PascalCase, relationship types UPPER_SNAKE_CASE

package/templates/stacks/nextjs.md

@@ -0,0 +1,184 @@
+# Next.js Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. App Router (Next.js 13+)
+
+```
+MANDATORY:
+  ├── Use the App Router (app/) — not Pages Router (pages/) for new projects
+  ├── Default to Server Components — add 'use client' ONLY when needed
+  ├── 'use client' needed for: useState, useEffect, event handlers, browser APIs
+  ├── Keep 'use client' boundary as low as possible — don't mark entire pages
+  └── NEVER import server-only code in client components
+```
+
+**BAD** — marking the whole page as client:
+```tsx
+'use client'; // ← Unnecessary — only the button needs interactivity
+export default function Page() {
+  return <div><h1>Static content</h1><LikeButton /></div>;
+}
+```
+
+**GOOD** — push client boundary down:
+```tsx
+// app/page.tsx — Server Component (default)
+export default function Page() {
+  return <div><h1>Static content</h1><LikeButton /></div>;
+}
+
+// components/LikeButton.tsx
+'use client';
+export function LikeButton() {
+  const [liked, setLiked] = useState(false);
+  return <button onClick={() => setLiked(!liked)}>Like</button>;
+}
+```
+
+---
+
+## 2. Data Fetching
+
+```
+MANDATORY:
+  ├── Server Components: fetch directly (async component) — no useEffect
+  ├── Client Components: React Query for server data — same as react.md Section 1
+  ├── Use Route Handlers (app/api/) for API endpoints — not pages/api/
+  ├── Set revalidate or cache options on server-side fetches
+  └── NEVER fetch from your own API routes in Server Components — call the function directly
+```
+
+**BAD** — Server Component calling its own API:
+```tsx
+// app/page.tsx
+const res = await fetch('http://localhost:3000/api/users'); // calling yourself!
+```
+
+**GOOD** — call the data function directly:
+```tsx
+// app/page.tsx
+import { getUsers } from '@/lib/data/users';
+export default async function Page() {
+  const users = await getUsers();
+  return <UserList users={users} />;
+}
+```
+
+---
+
+## 3. Route Structure
+
+```
+MANDATORY:
+  ├── app/{route}/page.tsx — page component
+  ├── app/{route}/layout.tsx — shared layout (wraps child pages)
+  ├── app/{route}/loading.tsx — Suspense fallback for the route
+  ├── app/{route}/error.tsx — error boundary for the route ('use client')
+  ├── app/{route}/not-found.tsx — 404 for the route
+  ├── Group routes with (parentheses) for layout grouping: app/(auth)/login
+  └── Dynamic routes: app/users/[id]/page.tsx
+```
+
+---
+
+## 4. Server Actions
+
+```
+MANDATORY (Next.js 14+):
+  ├── Use Server Actions for form mutations — not client-side API calls
+  ├── Mark with 'use server' at the top of the function or file
+  ├── Validate ALL inputs with Zod — Server Actions are public endpoints
+  ├── Return typed results — not raw responses
+  └── Revalidate cache after mutations: revalidatePath() or revalidateTag()
+```
+
+**GOOD**
+```tsx
+'use server';
+import { z } from 'zod';
+import { revalidatePath } from 'next/cache';
+
+const schema = z.object({ name: z.string().min(2), email: z.string().email() });
+
+export async function createUser(formData: FormData) {
+  const parsed = schema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) return { error: parsed.error.flatten() };
+
+  await db.user.create({ data: parsed.data });
+  revalidatePath('/users');
+  return { success: true };
+}
+```
+
+---
+
+## 5. Environment Variables
+
+```
+MANDATORY:
+  ├── NEXT_PUBLIC_ prefix for client-exposed vars — all others are server-only
+  ├── NEVER put secrets in NEXT_PUBLIC_ vars — they're in the client bundle
+  ├── Access server-only vars in Server Components, Route Handlers, Server Actions
+  ├── Validate env vars at startup with t3-env or manual checks
+  └── .env.local in .gitignore — commit .env.example with placeholder values
+```
+
+---
+
+## 6. Metadata and SEO
+
+```
+MANDATORY:
+  ├── Export metadata object or generateMetadata function from page.tsx
+  ├── Every page needs title and description at minimum
+  ├── Use template for consistent titles: { template: '%s | AppName' }
+  ├── Set Open Graph and Twitter card metadata for shared pages
+  └── Add robots.txt and sitemap.xml via app/robots.ts and app/sitemap.ts
+```
+
+---
+
+## 7. Middleware
+
+```
+WHEN NEEDED:
+  ├── Use middleware.ts at project root for auth redirects, geolocation, headers
+  ├── Keep middleware fast — it runs on EVERY request matching the matcher
+  ├── Use matcher config to limit which routes trigger middleware
+  ├── NEVER do heavy computation or database calls in middleware
+  └── Use NextResponse.next() to continue, NextResponse.redirect() to redirect
+```
+
+---
+
+## 8. Anti-Patterns
+
+```
+NEVER:
+  ├── 'use client' on entire pages when only a small part needs interactivity
+  ├── useEffect + fetch in components when a Server Component would work
+  ├── Fetching your own API routes from Server Components
+  ├── Server Actions without input validation — they're public endpoints
+  ├── Secrets in NEXT_PUBLIC_ env vars
+  ├── getServerSideProps / getStaticProps (Pages Router) in App Router projects
+  ├── Importing server-only modules (fs, db) in 'use client' components
+  └── Massive layouts that re-render on every navigation
+```
+
+---
+
+## Next.js Verification Checklist
+
+- [ ] App Router used (app/ directory)
+- [ ] Server Components by default — 'use client' only where needed
+- [ ] Client boundary pushed as low as possible
+- [ ] Server fetches call functions directly — not own API routes
+- [ ] Server Actions validate input with Zod
+- [ ] Cache revalidated after mutations
+- [ ] Every page has metadata (title + description)
+- [ ] loading.tsx and error.tsx for each major route
+- [ ] No secrets in NEXT_PUBLIC_ vars
+- [ ] Middleware is fast and uses matcher config