@sibyllinesoft/arbiter 0.1.0

package/dist/templates/plopfiles/_modules/docs/mkdocs/templates/scripts/aggregate-docs.mjs.hbs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * Documentation Aggregator
+ *
+ * Collects documentation from all subprojects and builds a unified docs site.
+ * Supports TSDoc/JSDoc extraction for TypeScript/JavaScript projects.
+ */
+
+import { existsSync, mkdirSync, cpSync, readdirSync, statSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname, basename, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, '..');
+const docsDir = join(projectRoot, 'docs');
+
+// Subproject directories to scan for docs
+const subprojectDirs = [
+{{#each modules}}
+  '{{this}}',
+{{/each}}
+];
+
+// File patterns to look for documentation
+const docPatterns = [
+  'README.md',
+  'CHANGELOG.md',
+  'docs/**/*.md',
+  'api-docs/**/*.md',
+];
+
+/**
+ * Copy documentation files from subproject to main docs
+ */
+function aggregateSubprojectDocs(subproject) {
+  const subprojectPath = join(projectRoot, subproject);
+  const targetPath = join(docsDir, 'reference', subproject);
+
+  if (!existsSync(subprojectPath)) {
+    console.warn(`Subproject not found: ${subproject}`);
+    return;
+  }
+
+  // Create target directory
+  mkdirSync(targetPath, { recursive: true });
+
+  // Copy README as index
+  const readmePath = join(subprojectPath, 'README.md');
+  if (existsSync(readmePath)) {
+    cpSync(readmePath, join(targetPath, 'index.md'));
+    console.log(`  Copied README from ${subproject}`);
+  }
+
+  // Copy docs folder if exists
+  const subDocsPath = join(subprojectPath, 'docs');
+  if (existsSync(subDocsPath) && statSync(subDocsPath).isDirectory()) {
+    cpSync(subDocsPath, targetPath, { recursive: true });
+    console.log(`  Copied docs/ from ${subproject}`);
+  }
+
+  // Generate API reference from TypeScript/JavaScript
+  const srcPath = join(subprojectPath, 'src');
+  if (existsSync(srcPath)) {
+    generateApiReference(srcPath, join(targetPath, 'api'));
+  }
+}
+
+/**
+ * Generate API reference from source files
+ */
+function generateApiReference(srcPath, outputPath) {
+  mkdirSync(outputPath, { recursive: true });
+
+  const files = findSourceFiles(srcPath);
+  const apiIndex = [];
+
+  for (const file of files) {
+    const relativePath = relative(srcPath, file);
+    const docs = extractDocs(file);
+
+    if (docs.length > 0) {
+      const mdContent = generateMarkdown(relativePath, docs);
+      const outputFile = join(outputPath, relativePath.replace(/\.[jt]sx?$/, '.md'));
+
+      mkdirSync(dirname(outputFile), { recursive: true });
+      writeFileSync(outputFile, mdContent);
+
+      apiIndex.push({ path: relativePath, exports: docs.map(d => d.name) });
+    }
+  }
+
+  // Generate API index
+  if (apiIndex.length > 0) {
+    const indexContent = generateApiIndex(apiIndex);
+    writeFileSync(join(outputPath, 'index.md'), indexContent);
+  }
+}
+
+/**
+ * Find all TypeScript/JavaScript source files
+ */
+function findSourceFiles(dir, files = []) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
+      findSourceFiles(fullPath, files);
+    } else if (entry.isFile() && /\.[jt]sx?$/.test(entry.name) && !entry.name.includes('.test.') && !entry.name.includes('.spec.')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Extract documentation from source file (basic TSDoc/JSDoc parser)
+ */
+function extractDocs(filePath) {
+  const content = readFileSync(filePath, 'utf-8');
+  const docs = [];
+
+  // Match JSDoc/TSDoc comments followed by exports
+  const docPattern = /\/\*\*\s*([\s\S]*?)\s*\*\/\s*(?:export\s+(?:async\s+)?(?:function|const|class|interface|type)\s+(\w+))/g;
+
+  let match;
+  while ((match = docPattern.exec(content)) !== null) {
+    const [, docContent, name] = match;
+    docs.push({
+      name,
+      description: parseDocComment(docContent),
+    });
+  }
+
+  return docs;
+}
+
+/**
+ * Parse JSDoc comment into structured data
+ */
+function parseDocComment(comment) {
+  const lines = comment.split('\n').map(l => l.replace(/^\s*\*\s?/, '').trim());
+  return lines.filter(l => !l.startsWith('@')).join('\n').trim();
+}
+
+/**
+ * Generate Markdown from documentation
+ */
+function generateMarkdown(path, docs) {
+  let content = `# ${basename(path, '.ts')}\n\n`;
+  content += `Source: \`${path}\`\n\n`;
+
+  for (const doc of docs) {
+    content += `## ${doc.name}\n\n`;
+    content += `${doc.description || 'No description available.'}\n\n`;
+  }
+
+  return content;
+}
+
+/**
+ * Generate API index page
+ */
+function generateApiIndex(apiIndex) {
+  let content = '# API Reference\n\n';
+  content += 'Auto-generated API documentation.\n\n';
+
+  for (const { path, exports } of apiIndex) {
+    const mdPath = path.replace(/\.[jt]sx?$/, '.md');
+    content += `## [${basename(path)}](${mdPath})\n\n`;
+    content += exports.map(e => `- \`${e}\``).join('\n') + '\n\n';
+  }
+
+  return content;
+}
+
+// Main execution
+console.log('Aggregating documentation from subprojects...\n');
+
+for (const subproject of subprojectDirs) {
+  console.log(`Processing: ${subproject}`);
+  aggregateSubprojectDocs(subproject);
+}
+
+console.log('\nDocumentation aggregation complete!');
+console.log('Run "mkdocs serve" to preview the docs.');

package/dist/templates/plopfiles/_modules/docs/mkdocs/templates/scripts/gen_ref_pages.py.hbs

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+Generate API reference pages for MkDocs.
+
+This script is run by mkdocs-gen-files plugin to auto-generate
+API documentation from Python source code.
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+# Python source directories to document
+SRC_DIRS = [
+    "backend/app",
+]
+
+nav = mkdocs_gen_files.Nav()
+
+for src_dir in SRC_DIRS:
+    src_path = Path(src_dir)
+
+    if not src_path.exists():
+        continue
+
+    for path in sorted(src_path.rglob("*.py")):
+        # Skip private modules and tests
+        if path.name.startswith("_") or "test" in path.name:
+            continue
+
+        module_path = path.relative_to(src_path.parent).with_suffix("")
+        doc_path = path.relative_to(src_path.parent).with_suffix(".md")
+        full_doc_path = Path("reference", doc_path)
+
+        parts = tuple(module_path.parts)
+
+        if parts[-1] == "__init__":
+            parts = parts[:-1]
+            doc_path = doc_path.with_name("index.md")
+            full_doc_path = full_doc_path.with_name("index.md")
+
+        if not parts:
+            continue
+
+        nav[parts] = doc_path.as_posix()
+
+        with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+            identifier = ".".join(parts)
+            fd.write(f"::: {identifier}\n")
+
+        mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

package/dist/templates/plopfiles/_modules/frontends/react-vite/module.js

@@ -0,0 +1,60 @@
+/**
+ * React + Vite Frontend Module
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templatesDir = resolve(__dirname, "templates");
+
+export default function (data) {
+  const frontendDir = data.frontendDir || "frontend";
+
+  return [
+    {
+      type: "addMany",
+      destination: `{{projectDir}}/${frontendDir}`,
+      base: templatesDir,
+      templateFiles: `${templatesDir}/**/*.hbs`,
+      stripExtensions: ["hbs"],
+      data,
+    },
+  ];
+}
+
+export const description = "React frontend with Vite, TypeScript, and Tailwind CSS";
+
+export const dependencies = {
+  react: "^18.2.0",
+  "react-dom": "^18.2.0",
+  "react-router-dom": "^6.20.0",
+  "@tanstack/react-query": "^5.0.0",
+};
+
+export const devDependencies = {
+  "@types/react": "^18.2.0",
+  "@types/react-dom": "^18.2.0",
+  "@vitejs/plugin-react": "^4.2.0",
+  autoprefixer: "^10.4.0",
+  postcss: "^8.4.0",
+  tailwindcss: "^3.4.0",
+  typescript: "^5.3.0",
+  vite: "^5.0.0",
+  "@biomejs/biome": "^1.9.0",
+  typedoc: "^0.27.0",
+};
+
+export const scripts = {
+  "dev:frontend": "vite --config frontend/vite.config.ts",
+  "build:frontend": "vite build --config frontend/vite.config.ts",
+  "preview:frontend": "vite preview --config frontend/vite.config.ts",
+  "lint:frontend": "biome check frontend",
+  "lint:frontend:fix": "biome check --write frontend",
+  "test:frontend": "vitest run --config frontend/vite.config.ts",
+  "docs:frontend": "typedoc --out docs/api/frontend frontend/src",
+};
+
+export const envVars = {
+  VITE_API_URL: "http://localhost:3000",
+};

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/index.html.hbs

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{titleCase name}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/nginx.conf.hbs

@@ -0,0 +1,31 @@
+server {
+    listen 80;
+    server_name localhost;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Handle SPA routing
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Proxy API requests to backend
+    location /api {
+        proxy_pass http://{{kebabCase name}}-backend:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_cache_bypass $http_upgrade;
+    }
+
+    # Cache static assets
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # Gzip compression
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+}

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/postcss.config.js.hbs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/src/App.tsx.hbs

@@ -0,0 +1,12 @@
+import { Routes, Route } from "react-router-dom";
+import { Home } from "./pages/Home";
+
+export function App() {
+  return (
+    <div className="min-h-screen bg-gray-50">
+      <Routes>
+        <Route path="/" element={<Home />} />
+      </Routes>
+    </div>
+  );
+}

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/src/index.css.hbs

@@ -0,0 +1,25 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+}

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/src/lib/api.ts.hbs

@@ -0,0 +1,52 @@
+const API_URL = import.meta.env.VITE_API_URL || "";
+
+class ApiClient {
+  private baseUrl: string;
+
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl;
+  }
+
+  private async request(path: string, options: RequestInit = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options.headers,
+      },
+    });
+
+    if (!response.ok) {
+      throw new Error(`API error: ${response.status} ${response.statusText}`);
+    }
+
+    return response;
+  }
+
+  get(path: string, options?: RequestInit) {
+    return this.request(path, { ...options, method: "GET" });
+  }
+
+  post(path: string, data?: unknown, options?: RequestInit) {
+    return this.request(path, {
+      ...options,
+      method: "POST",
+      body: data ? JSON.stringify(data) : undefined,
+    });
+  }
+
+  put(path: string, data?: unknown, options?: RequestInit) {
+    return this.request(path, {
+      ...options,
+      method: "PUT",
+      body: data ? JSON.stringify(data) : undefined,
+    });
+  }
+
+  delete(path: string, options?: RequestInit) {
+    return this.request(path, { ...options, method: "DELETE" });
+  }
+}
+
+export const api = new ApiClient(API_URL);

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/src/main.tsx.hbs

@@ -0,0 +1,18 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { BrowserRouter } from "react-router-dom";
+import { App } from "./App";
+import "./index.css";
+
+const queryClient = new QueryClient();
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <App />
+      </BrowserRouter>
+    </QueryClientProvider>
+  </React.StrictMode>
+);

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/src/pages/Home.tsx.hbs

@@ -0,0 +1,31 @@
+import { useQuery } from "@tanstack/react-query";
+import { api } from "../lib/api";
+
+export function Home() {
+  const { data: health, isLoading, error } = useQuery({
+    queryKey: ["health"],
+    queryFn: () => api.get("/health").then((res) => res.json()),
+    retry: false,
+  });
+
+  return (
+    <div className="container mx-auto px-4 py-8">
+      <h1 className="text-4xl font-bold mb-6">{{titleCase name}}</h1>
+
+      <div className="bg-white rounded-lg shadow p-6">
+        <h2 className="text-xl font-semibold mb-4">API Status</h2>
+        {isLoading && <p className="text-gray-500">Checking API...</p>}
+        {error && (
+          <p className="text-red-500">
+            API not reachable. Make sure the backend is running.
+          </p>
+        )}
+        {health && (
+          <p className="text-green-500">
+            API is healthy: {JSON.stringify(health)}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/tailwind.config.js.hbs

@@ -0,0 +1,8 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/tsconfig.json.hbs

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/tsconfig.node.json.hbs

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}

package/dist/templates/plopfiles/_modules/frontends/react-vite/templates/vite.config.ts.hbs

@@ -0,0 +1,21 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "path";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  server: {
+    port: 5173,
+    proxy: {
+      "/api": {
+        target: process.env.VITE_API_URL || "http://localhost:3000",
+        changeOrigin: true,
+      },
+    },
+  },
+});

package/dist/templates/plopfiles/_modules/frontends/solid-vite/module.js

@@ -0,0 +1,51 @@
+/**
+ * Solid + Vite Frontend Module
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templatesDir = resolve(__dirname, "templates");
+
+export default function (data) {
+  const frontendDir = data.frontendDir || "frontend";
+
+  return [
+    {
+      type: "addMany",
+      destination: `{{projectDir}}/${frontendDir}`,
+      base: templatesDir,
+      templateFiles: `${templatesDir}/**/*.hbs`,
+      stripExtensions: ["hbs"],
+      data,
+    },
+  ];
+}
+
+export const description = "SolidJS frontend with Vite, TypeScript, and Tailwind CSS";
+
+export const dependencies = {
+  "solid-js": "^1.8.0",
+  "@solidjs/router": "^0.10.0",
+  "@tanstack/solid-query": "^5.0.0",
+};
+
+export const devDependencies = {
+  "vite-plugin-solid": "^2.8.0",
+  autoprefixer: "^10.4.0",
+  postcss: "^8.4.0",
+  tailwindcss: "^3.4.0",
+  typescript: "^5.3.0",
+  vite: "^5.0.0",
+};
+
+export const scripts = {
+  "dev:frontend": "vite --config frontend/vite.config.ts",
+  "build:frontend": "vite build --config frontend/vite.config.ts",
+  "preview:frontend": "vite preview --config frontend/vite.config.ts",
+};
+
+export const envVars = {
+  VITE_API_URL: "http://localhost:3000",
+};

package/dist/templates/plopfiles/_modules/frontends/solid-vite/templates/index.html.hbs

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{titleCase name}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>

package/dist/templates/plopfiles/_modules/frontends/solid-vite/templates/postcss.config.js.hbs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/dist/templates/plopfiles/_modules/frontends/solid-vite/templates/src/App.tsx.hbs

@@ -0,0 +1,12 @@
+import { Route, Routes } from "@solidjs/router";
+import { Home } from "./pages/Home";
+
+export default function App() {
+  return (
+    <div class="min-h-screen bg-gray-50">
+      <Routes>
+        <Route path="/" component={Home} />
+      </Routes>
+    </div>
+  );
+}

package/dist/templates/plopfiles/_modules/frontends/solid-vite/templates/src/index.css.hbs

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

package/dist/templates/plopfiles/_modules/frontends/solid-vite/templates/src/index.tsx.hbs

@@ -0,0 +1,21 @@
+/* @refresh reload */
+import { render } from "solid-js/web";
+import { Router } from "@solidjs/router";
+import { QueryClient, QueryClientProvider } from "@tanstack/solid-query";
+import App from "./App";
+import "./index.css";
+
+const queryClient = new QueryClient();
+
+const root = document.getElementById("root");
+
+render(
+  () => (
+    <QueryClientProvider client={queryClient}>
+      <Router>
+        <App />
+      </Router>
+    </QueryClientProvider>
+  ),
+  root!
+);