forgedev 1.1.3 → 1.3.0

package/templates/docs-portal/nextjs/src/components/portal/mobile-portal-nav.tsx

@@ -0,0 +1,81 @@
+'use client';
+
+import { useState } from 'react';
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+
+interface NavCategory {
+  id: string;
+  label: string;
+  icon: string;
+  docs: { slug: string; title: string }[];
+}
+
+export function MobilePortalNav({ categories }: { categories: NavCategory[] }) {
+  const pathname = usePathname();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button
+        onClick={() => setOpen(!open)}
+        className="p-2 rounded-lg text-gray-600 hover:bg-gray-100 transition-colors"
+        aria-label="Toggle navigation menu"
+      >
+        {open ? (
+          <svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
+          </svg>
+        ) : (
+          <svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6h16M4 12h16M4 18h16" />
+          </svg>
+        )}
+      </button>
+
+      {open && (
+        <div className="absolute top-full left-0 right-0 bg-white border-b border-gray-200 shadow-lg z-50">
+          <div className="max-w-7xl mx-auto px-4 py-4 space-y-2">
+            <Link
+              href="/portal"
+              onClick={() => setOpen(false)}
+              className={`block px-3 py-2 rounded-lg text-sm font-medium transition-colors ${
+                pathname === '/portal'
+                  ? 'bg-gray-100 text-gray-900'
+                  : 'text-gray-600 hover:bg-gray-50'
+              }`}
+            >
+              Overview
+            </Link>
+            {categories.map((cat) => (
+              <div key={cat.id} className="space-y-1">
+                <Link
+                  href={`/portal/${cat.id}`}
+                  onClick={() => setOpen(false)}
+                  className={`block px-3 py-2 rounded-lg text-sm font-medium transition-colors ${
+                    pathname.startsWith(`/portal/${cat.id}`)
+                      ? 'bg-gray-100 text-gray-900'
+                      : 'text-gray-600 hover:bg-gray-50'
+                  }`}
+                >
+                  <span className="mr-2">{cat.icon}</span>
+                  {cat.label}
+                </Link>
+                {cat.docs.map((doc) => (
+                  <Link
+                    key={doc.slug}
+                    href={`/portal/${cat.id}/${doc.slug}`}
+                    onClick={() => setOpen(false)}
+                    className="block pl-8 pr-3 py-1.5 text-sm text-gray-500 hover:text-gray-900 hover:bg-gray-50 rounded-lg transition-colors"
+                  >
+                    {doc.title}
+                  </Link>
+                ))}
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </>
+  );
+}

package/templates/docs-portal/nextjs/src/components/portal/portal-nav.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+import { useState, useRef, useEffect } from 'react';
+
+interface NavCategory {
+  id: string;
+  label: string;
+  icon: string;
+  docs: { slug: string; title: string }[];
+}
+
+export function PortalNav({ categories }: { categories: NavCategory[] }) {
+  const pathname = usePathname();
+  const [openMenu, setOpenMenu] = useState<string | null>(null);
+  const navRef = useRef<HTMLElement>(null);
+
+  // Close dropdown when clicking outside
+  useEffect(() => {
+    function handleClickOutside(e: MouseEvent) {
+      if (navRef.current && !navRef.current.contains(e.target as Node)) {
+        setOpenMenu(null);
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  return (
+    <nav ref={navRef} className="flex items-center gap-1">
+      <Link
+        href="/portal"
+        className={`px-3 py-2 rounded-lg text-sm font-medium transition-colors ${
+          pathname === '/portal'
+            ? 'bg-gray-100 text-gray-900'
+            : 'text-gray-600 hover:text-gray-900 hover:bg-gray-50'
+        }`}
+      >
+        Overview
+      </Link>
+      {categories.map((cat) => (
+        <div
+          key={cat.id}
+          className="relative"
+          onMouseEnter={() => setOpenMenu(cat.id)}
+          onMouseLeave={() => setOpenMenu(null)}
+        >
+          <button
+            aria-expanded={openMenu === cat.id}
+            aria-haspopup="true"
+            onClick={() => setOpenMenu(openMenu === cat.id ? null : cat.id)}
+            onKeyDown={(e) => {
+              if (e.key === 'Escape') setOpenMenu(null);
+            }}
+            className={`px-3 py-2 rounded-lg text-sm font-medium transition-colors flex items-center gap-1.5 ${
+              pathname.startsWith(`/portal/${cat.id}`)
+                ? 'bg-gray-100 text-gray-900'
+                : 'text-gray-600 hover:text-gray-900 hover:bg-gray-50'
+            }`}
+          >
+            <span>{cat.icon}</span>
+            <span>{cat.label}</span>
+            <svg className="w-3.5 h-3.5 opacity-50" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
+            </svg>
+          </button>
+          {openMenu === cat.id && cat.docs.length > 0 && (
+            <div role="menu" className="absolute top-full left-0 mt-1 w-64 bg-white rounded-xl shadow-lg border border-gray-200 py-2 z-50">
+              {cat.docs.map((doc) => (
+                <Link
+                  key={doc.slug}
+                  role="menuitem"
+                  href={`/portal/${cat.id}/${doc.slug}`}
+                  className="block px-4 py-2.5 text-sm text-gray-700 hover:bg-gray-50 hover:text-gray-900 transition-colors"
+                >
+                  {doc.title}
+                </Link>
+              ))}
+            </div>
+          )}
+        </div>
+      ))}
+    </nav>
+  );
+}

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

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_DB: {{PROJECT_NAME_SNAKE}}
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: {{LINT_COMMAND}}
+
+      - name: Type check
+        run: {{TYPE_CHECK_COMMAND}}
+
+      - name: Build
+        run: {{BUILD_COMMAND}}
+
+      - name: Test
+        run: {{TEST_COMMAND}}
+        env:
+          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/{{PROJECT_NAME_SNAKE}}

package/templates/testing/pytest/backend/tests/conftest.py.template

@@ -0,0 +1,11 @@
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+from app.main import app
+
+
+@pytest.fixture
+async def client():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as ac:
+        yield ac

package/templates/testing/pytest/backend/tests/test_health.py.template

@@ -0,0 +1,10 @@
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_health_endpoint(client):
+    response = await client.get("/health")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["status"] == "ok"
+    assert data["service"] == "{{PROJECT_NAME}}"

package/templates/testing/vitest/vitest.config.ts.template

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.{ts,tsx}'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+});