@tekyzinc/gsd-t 2.46.11 → 2.50.10

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

package/templates/stacks/node-api.md

@@ -0,0 +1,196 @@
+# Node.js API Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Service Layer Pattern
+
+HTTP knowledge belongs in services only. Controllers are thin delegators.
+
+```
+MANDATORY:
+  ├── Controllers: validate input, call service, return response — nothing else
+  ├── Services: all business logic, data access, external HTTP calls
+  └── Never import axios/fetch in controllers, hooks, or UI components
+```
+
+**BAD:** `router.get('/users/:id', async (req, res) => { const r = await axios.get(...); res.json(r.data); })`
+
+**GOOD:**
+```js
+// controller — delegates only
+router.get('/users/:id', async (req, res, next) => {
+  try { res.json({ data: await userService.getById(req.params.id) }); }
+  catch (err) { next(err); }
+});
+```
+
+---
+
+## 2. Request Validation
+
+Every endpoint must validate input. Reject unexpected fields.
+
+```
+MANDATORY:
+  ├── Validate bodies, path params, and query strings with Zod or Joi schemas
+  ├── Use .strict() (Zod) or .unknown(false) (Joi) — reject extra fields
+  └── Return 400 with structured error before business logic runs
+```
+
+**BAD:** `await orderService.create(req.body)` — raw unvalidated input
+
+**GOOD:**
+```js
+const schema = z.object({ productId: z.string().uuid(), quantity: z.number().int().min(1) }).strict();
+router.post('/orders', validate(schema), async (req, res, next) => { ... });
+```
+
+---
+
+## 3. Response Formatting
+
+All endpoints return a consistent shape.
+
+```
+Success: { data: T, meta?: { page, total } }
+Error:   { error: { code: string, message: string } }
+Never return raw objects, arrays, or strings at the top level.
+```
+
+---
+
+## 4. Error Handling
+
+```
+MANDATORY:
+  ├── Register a global error handler middleware as the last app.use()
+  ├── All route handlers call next(err) on caught errors — never swallow
+  ├── No empty catch blocks — log at minimum, then re-throw or next(err)
+  ├── Log full error server-side; return sanitized response to client
+  └── Never include stack traces in production responses
+```
+
+**Global error handler:**
+```js
+app.use((err, req, res, next) => {
+  logger.error({ err, path: req.path });
+  const status = err.statusCode ?? 500;
+  const message = process.env.NODE_ENV === 'production' && status === 500
+    ? 'Internal server error' : err.message;
+  res.status(status).json({ error: { code: err.code ?? 'ERR_INTERNAL', message } });
+});
+```
+
+---
+
+## 5. Middleware Order
+
+Register in this exact order:
+
+```
+1. Security headers (helmet)
+2. CORS — see _security.md
+3. Body parser (express.json with size limit)
+4. Request/correlation ID
+5. Auth middleware — see _security.md
+6. Rate limiting — see _security.md
+7. Route-level validation
+8. Route handlers
+9. 404 handler
+10. Global error handler (last)
+```
+
+---
+
+## 6. Environment Config
+
+```
+MANDATORY:
+  ├── All config from environment variables — no hardcoded values
+  ├── Never commit .env files with real values
+  ├── Client-side vars: VITE_ or NEXT_PUBLIC_ prefix only
+  ├── Never expose server secrets (DB_PASSWORD, API_KEY) to client bundles
+  └── Validate required env vars on startup — fail fast if missing
+```
+
+**BAD:** `new Pool({ password: 'hardcoded123' })`
+
+**GOOD:**
+```js
+['DATABASE_URL', 'JWT_SECRET'].forEach(k => {
+  if (!process.env[k]) throw new Error(`Missing env: ${k}`);
+});
+```
+
+---
+
+## 7. Structured Logging
+
+```
+MANDATORY:
+  ├── Use structured JSON logging (pino or winston with json transport)
+  ├── Never log PII — redact email, name, phone, tokens before logging
+  ├── Include request ID on every log line for traceability
+  └── No console.log in production paths
+```
+
+**BAD:** `console.log('User:', user)` — leaks PII
+
+**GOOD:** `logger.info({ userId: user.id, action: 'login' }, 'User authenticated')`
+
+---
+
+## 8. Health Check Endpoint
+
+```js
+app.get('/health', (req, res) =>
+  res.json({ status: 'ok', uptime: process.uptime() }));
+// /health/ready — also checks DB/dependency reachability
+```
+
+---
+
+## 9. Graceful Shutdown
+
+```
+MANDATORY:
+  ├── Handle SIGTERM and SIGINT
+  ├── Stop accepting new connections immediately
+  ├── Drain in-flight requests (10s timeout)
+  └── Close DB pools before exiting
+```
+
+```js
+const shutdown = async () => {
+  server.close(async () => { await db.end(); process.exit(0); });
+  setTimeout(() => process.exit(1), 10_000).unref();
+};
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+```
+
+---
+
+## 10. Security Cross-References
+
+These topics are covered in `_security.md` — do not duplicate here:
+SQL injection, auth token storage, CORS, Content Security Policy, rate limiting, input sanitization.
+
+---
+
+## Verification Checklist
+
+- [ ] Route handlers delegate all logic to services — no business logic in controllers
+- [ ] Every endpoint has a Zod/Joi schema with strict mode (no extra fields allowed)
+- [ ] All responses use `{ data }` or `{ error: { code, message } }` shape
+- [ ] Global error handler registered last — no route handles errors via `res.json` directly
+- [ ] No stack traces in production responses
+- [ ] No silent catch blocks — all errors are logged or re-thrown
+- [ ] All config from env vars — no hardcoded secrets or connection strings
+- [ ] Structured JSON logging in use — no `console.log` in production paths
+- [ ] No PII in log output
+- [ ] `/health` endpoint returns 200 with status payload
+- [ ] SIGTERM/SIGINT handlers registered with connection draining
+- [ ] Security concerns (SQL injection, CORS, tokens) deferred to `_security.md`