forgedev 1.2.0 → 1.4.0

package/templates/docs-portal/nextjs/src/lib/docs.ts

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface DocFile {
+  slug: string;
+  title: string;
+  content: string;
+  category: string;
+  categoryLabel: string;
+  lastModified: Date;
+}
+
+export interface DocCategory {
+  id: string;
+  label: string;
+  description: string;
+  icon: string;
+  docs: { slug: string; title: string }[];
+}
+
+const DOCS_ROOT = path.join(process.cwd(), 'docs');
+
+const CATEGORY_META: Record<string, { label: string; description: string; icon: string; order: number }> = {
+  prd: { label: 'Product', description: 'Product requirements and roadmap', icon: '📋', order: 1 },
+  sdd: { label: 'Architecture', description: 'System design and technical architecture', icon: '🏗️', order: 2 },
+  uat: { label: 'Testing', description: 'Test plans, results, and acceptance criteria', icon: '✅', order: 3 },
+  sessions: { label: 'Session Logs', description: 'Testing session results and bug reports', icon: '📝', order: 4 },
+};
+
+function extractTitle(content: string, filename: string): string {
+  // Try to get title from first H1
+  const match = content.match(/^#\s+(.+)$/m);
+  if (match) return match[1];
+
+  // Fall back to filename
+  return filename
+    .replace(/\.md$/, '')
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+export function getCategories(): DocCategory[] {
+  if (!fs.existsSync(DOCS_ROOT)) return [];
+
+  const categories: DocCategory[] = [];
+  const entries = fs.readdirSync(DOCS_ROOT, { withFileTypes: true });
+
+  // Categorized docs (in subdirectories)
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const categoryId = entry.name;
+    const categoryDir = path.join(DOCS_ROOT, categoryId);
+    const meta = CATEGORY_META[categoryId] || {
+      label: categoryId.charAt(0).toUpperCase() + categoryId.slice(1),
+      description: '',
+      icon: '📄',
+      order: 99,
+    };
+
+    const files = fs.readdirSync(categoryDir).filter((f) => f.endsWith('.md'));
+    if (files.length === 0) continue;
+
+    const docs = files.map((f) => {
+      const raw = fs.readFileSync(path.join(categoryDir, f), 'utf-8');
+      return {
+        slug: f.replace(/\.md$/, ''),
+        title: extractTitle(raw, f),
+      };
+    });
+
+    categories.push({ id: categoryId, ...meta, docs });
+  }
+
+  // Top-level markdown files go into a "General" category
+  const topLevelFiles = entries.filter((e) => !e.isDirectory() && e.name.endsWith('.md'));
+  if (topLevelFiles.length > 0) {
+    const docs = topLevelFiles.map((f) => {
+      const raw = fs.readFileSync(path.join(DOCS_ROOT, f.name), 'utf-8');
+      return {
+        slug: f.name.replace(/\.md$/, ''),
+        title: extractTitle(raw, f.name),
+      };
+    });
+    categories.push({
+      id: '_general',
+      label: 'General',
+      description: 'Project documentation',
+      icon: '📄',
+      docs,
+    });
+  }
+
+  // Sort by configured order
+  return categories.sort((a, b) => {
+    const orderA = CATEGORY_META[a.id]?.order ?? 99;
+    const orderB = CATEGORY_META[b.id]?.order ?? 99;
+    return orderA - orderB;
+  });
+}
+
+export function getDoc(category: string, slug: string): DocFile | null {
+  const dirPath = category === '_general' ? DOCS_ROOT : path.join(DOCS_ROOT, category);
+  const filePath = path.join(dirPath, `${slug}.md`);
+
+  // Prevent path traversal — resolved path must stay within DOCS_ROOT
+  const resolved = path.resolve(filePath);
+  const docsRoot = path.resolve(DOCS_ROOT);
+  if (!resolved.startsWith(docsRoot + path.sep)) return null;
+
+  if (!fs.existsSync(filePath)) return null;
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const stat = fs.statSync(filePath);
+  const meta = CATEGORY_META[category] || { label: 'General', description: '', icon: '📄', order: 99 };
+
+  return {
+    slug,
+    title: extractTitle(content, `${slug}.md`),
+    content,
+    category,
+    categoryLabel: meta.label,
+    lastModified: stat.mtime,
+  };
+}
+
+export function getAllDocs(): DocFile[] {
+  const categories = getCategories();
+  const docs: DocFile[] = [];
+
+  for (const cat of categories) {
+    for (const doc of cat.docs) {
+      const full = getDoc(cat.id, doc.slug);
+      if (full) docs.push(full);
+    }
+  }
+
+  return docs;
+}

package/templates/frontend/nextjs/package.json.template

@@ -21,7 +21,9 @@
     "react-dom": "^19.1.0",
     "@prisma/client": "^6.6.0",
     "clsx": "^2.1.1",
-    "tailwind-merge": "^3.2.0"
+    "tailwind-merge": "^3.2.0",
+    "react-markdown": "^9.0.3",
+    "remark-gfm": "^4.0.0"
   },
   "devDependencies": {
     "typescript": "^5.8.3",

package/templates/frontend/react/index.html.template

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{PROJECT_NAME_PASCAL}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/frontend/react/package.json.template

@@ -0,0 +1,34 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "react-router-dom": "^7.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@vitejs/plugin-react": "^4.4.0",
+    "vite": "^6.3.0",
+    "tailwindcss": "^4.1.3",
+    "@tailwindcss/vite": "^4.1.3",
+    "eslint": "^9.25.0",
+    "vitest": "^3.1.1",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/jest-dom": "^6.6.0",
+    "jsdom": "^26.0.0"
+  }
+}

package/templates/frontend/react/src/App.tsx.template

@@ -0,0 +1,10 @@
+export default function App() {
+  return (
+    <main className="min-h-screen flex items-center justify-center bg-gray-50">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold text-gray-900">{{PROJECT_NAME_PASCAL}}</h1>
+        <p className="mt-4 text-lg text-gray-600">{{STACK_DESCRIPTION}}</p>
+      </div>
+    </main>
+  );
+}

package/templates/frontend/react/src/index.css

@@ -0,0 +1 @@
+@import 'tailwindcss';

package/templates/frontend/react/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import './index.css';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/templates/frontend/react/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/templates/frontend/react/vite.config.ts.template

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3001',
+        changeOrigin: true,
+      },
+    },
+  },
+});

package/templates/frontend/react/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: [],
+  },
+});

package/templates/frontend/remix/app/root.tsx.template

@@ -0,0 +1,31 @@
+import {
+  Links,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+} from '@remix-run/react';
+import type { LinksFunction } from '@remix-run/node';
+import stylesheet from './tailwind.css?url';
+
+export const links: LinksFunction = () => [
+  { rel: 'stylesheet', href: stylesheet },
+];
+
+export default function App() {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <Outlet />
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}

package/templates/frontend/remix/app/routes/_index.tsx.template

@@ -0,0 +1,19 @@
+import type { MetaFunction } from '@remix-run/node';
+
+export const meta: MetaFunction = () => {
+  return [
+    { title: '{{PROJECT_NAME_PASCAL}}' },
+    { name: 'description', content: '{{STACK_DESCRIPTION}}' },
+  ];
+};
+
+export default function Index() {
+  return (
+    <main className="min-h-screen flex items-center justify-center bg-gray-50">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold text-gray-900">{{PROJECT_NAME_PASCAL}}</h1>
+        <p className="mt-4 text-lg text-gray-600">{{STACK_DESCRIPTION}}</p>
+      </div>
+    </main>
+  );
+}

package/templates/frontend/remix/app/routes/api.health.ts.template

@@ -0,0 +1,10 @@
+import { json } from '@remix-run/node';
+
+export function loader() {
+  return json({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),
+    service: '{{PROJECT_NAME}}',
+  });
+}

package/templates/frontend/remix/app/tailwind.css

@@ -0,0 +1 @@
+@import 'tailwindcss';

package/templates/frontend/remix/package.json.template

@@ -0,0 +1,39 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "remix vite:dev",
+    "build": "remix vite:build",
+    "start": "remix-serve ./build/server/index.js",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "db:push": "prisma db push",
+    "db:studio": "prisma studio",
+    "db:generate": "prisma generate"
+  },
+  "dependencies": {
+    "@remix-run/node": "^2.16.0",
+    "@remix-run/react": "^2.16.0",
+    "@remix-run/serve": "^2.16.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "isbot": "^5.1.0",
+    "@prisma/client": "^6.6.0"
+  },
+  "devDependencies": {
+    "@remix-run/dev": "^2.16.0",
+    "typescript": "^5.8.3",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "vite": "^6.3.0",
+    "tailwindcss": "^4.1.3",
+    "@tailwindcss/vite": "^4.1.3",
+    "eslint": "^9.25.0",
+    "prisma": "^6.6.0",
+    "vitest": "^3.1.1"
+  }
+}

package/templates/frontend/remix/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["@remix-run/node", "vite/client"]
+  },
+  "include": ["app", "env.d.ts"]
+}

package/templates/frontend/remix/vite.config.ts.template

@@ -0,0 +1,7 @@
+import { vitePlugin as remix } from '@remix-run/dev';
+import { defineConfig } from 'vite';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [remix(), tailwindcss()],
+});

package/templates/infra/github-actions/.github/workflows/ci.yml.template

@@ -43,6 +43,9 @@ jobs:
       - name: Type check
         run: {{TYPE_CHECK_COMMAND}}
 
+      - name: Build
+        run: {{BUILD_COMMAND}}
+
       - name: Test
         run: {{TEST_COMMAND}}
         env:

package/templates/infra/k8s/k8s/deployment.yml.template

@@ -0,0 +1,70 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{PROJECT_NAME}}
+  labels:
+    app: {{PROJECT_NAME}}
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: {{PROJECT_NAME}}
+  template:
+    metadata:
+      labels:
+        app: {{PROJECT_NAME}}
+    spec:
+      automountServiceAccountToken: false
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+        fsGroup: 1000
+      containers:
+        - name: {{PROJECT_NAME}}
+          image: {{PROJECT_NAME}}:{{IMAGE_TAG}}  # Update to match your CI-built image tag
+          imagePullPolicy: IfNotPresent
+          ports:
+            - containerPort: {{APP_PORT}}
+          env:
+            - name: PORT
+              value: "{{APP_PORT}}"
+            - name: DATABASE_URL
+              valueFrom:
+                secretKeyRef:
+                  name: {{PROJECT_NAME}}-secrets
+                  key: database-url
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          volumeMounts:
+            - name: tmp
+              mountPath: /tmp
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: {{APP_PORT}}
+            initialDelaySeconds: 10
+            periodSeconds: 15
+            timeoutSeconds: 5
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /healthz
+              port: {{APP_PORT}}
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 3
+          resources:
+            requests:
+              cpu: 100m
+              memory: 128Mi
+            limits:
+              cpu: 500m
+              memory: 512Mi
+      volumes:
+        - name: tmp
+          emptyDir: {}
+      terminationGracePeriodSeconds: 30

package/templates/infra/k8s/k8s/hpa.yml.template

@@ -0,0 +1,24 @@
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{PROJECT_NAME}}
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{PROJECT_NAME}}
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: 80

package/templates/infra/k8s/k8s/ingress.yml.template

@@ -0,0 +1,26 @@
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{PROJECT_NAME}}
+  annotations:
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
+    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
+    nginx.ingress.kubernetes.io/limit-rps: "10"
+    nginx.ingress.kubernetes.io/limit-connections: "5"
+spec:
+  ingressClassName: nginx
+  rules:
+    - host: {{PROJECT_NAME}}.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: {{PROJECT_NAME}}
+                port:
+                  number: 80
+  tls:
+    - hosts:
+        - {{PROJECT_NAME}}.example.com
+      secretName: {{PROJECT_NAME}}-tls

package/templates/infra/k8s/k8s/kustomization.yml.template

@@ -0,0 +1,13 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+namespace: {{PROJECT_NAME}}
+
+resources:
+  - namespace.yml
+  - deployment.yml
+  - service.yml
+  - ingress.yml
+  - secrets.yml
+  - hpa.yml
+  - networkpolicy.yml

package/templates/infra/k8s/k8s/namespace.yml.template

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: {{PROJECT_NAME}}

package/templates/infra/k8s/k8s/networkpolicy.yml.template

@@ -0,0 +1,41 @@
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: {{PROJECT_NAME}}
+spec:
+  podSelector:
+    matchLabels:
+      app: {{PROJECT_NAME}}
+  policyTypes:
+    - Ingress
+    - Egress
+  ingress:
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: ingress-nginx
+      ports:
+        - port: {{APP_PORT}}
+  egress:
+    # Database
+    - to:
+        - podSelector:
+            matchLabels:
+              app: postgres
+      ports:
+        - port: 5432
+    # DNS (UDP + TCP for large responses)
+    - to:
+        - namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: kube-system
+      ports:
+        - port: 53
+          protocol: UDP
+        - port: 53
+          protocol: TCP
+    # Uncomment to allow outbound HTTPS (external APIs, OAuth, webhooks)
+    # - to: []
+    #   ports:
+    #     - port: 443
+    #       protocol: TCP

package/templates/infra/k8s/k8s/secrets.yml.template

@@ -0,0 +1,10 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{PROJECT_NAME}}-secrets
+type: Opaque
+stringData:
+  # IMPORTANT: Replace these placeholder values before deploying.
+  # In production, use sealed-secrets, external-secrets, or your cloud provider's secret manager.
+  # Do NOT commit real credentials to version control.
+  database-url: "postgresql://USER:CHANGE_ME_BEFORE_DEPLOY@postgres:5432/{{PROJECT_NAME_SNAKE}}"

package/templates/infra/k8s/k8s/service.yml.template

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{PROJECT_NAME}}
+  labels:
+    app: {{PROJECT_NAME}}
+spec:
+  type: ClusterIP
+  selector:
+    app: {{PROJECT_NAME}}
+  ports:
+    - name: http
+      port: 80
+      targetPort: {{APP_PORT}}
+      protocol: TCP

package/templates/testing/load/k6/README.md.template

@@ -0,0 +1,48 @@
+# Load Testing — {{PROJECT_NAME_PASCAL}}
+
+Uses [k6](https://k6.io/) for load testing.
+
+## Setup
+
+```bash
+# macOS
+brew install k6
+
+# Windows (scoop)
+scoop install k6
+
+# Docker (no install)
+docker run --rm -i grafana/k6 run - <load-test.js
+```
+
+## Run
+
+```bash
+# Smoke test (quick, single request)
+k6 run --vus 1 --iterations 1 k6/load-test.js
+
+# Full load test against local server
+k6 run k6/load-test.js
+
+# Against staging
+k6 run -e BASE_URL=https://staging.example.com k6/load-test.js
+```
+
+## Thresholds
+
+| Metric | Threshold | Meaning |
+|--------|-----------|---------|
+| `http_req_duration p(95)` | < 500ms | 95th percentile response time |
+| `http_req_duration p(99)` | < 1.5s | 99th percentile response time |
+| `http_req_failed` | < 1% | Error rate |
+| `checks` | > 99% | Assertion pass rate |
+
+## CI Integration
+
+Add to your CI pipeline after deployment:
+
+```yaml
+- name: Load test
+  run: |
+    k6 run -e BASE_URL=${{ secrets.STAGING_URL }} k6/load-test.js
+```