h4ckath0n 0.1.0

package/bin/cli.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { copyDir, dirExists, generateSecret, validateProjectName, writeEnvFiles } from "../lib/scaffold.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function printUsage() {
+  console.log(`
+Usage: h4ckath0n <project-name> [options]
+
+Options:
+  --no-install   Skip dependency installation (uv sync / npm install)
+  --no-git       Skip git init
+  --no-python    Skip Python backend scaffolding
+  --no-node      Skip Node/React frontend scaffolding
+  --db <type>    Database type: postgres (default) or sqlite
+  -h, --help     Show this help message
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const opts = {
+    name: null,
+    install: true,
+    git: true,
+    python: true,
+    node: true,
+    db: "postgres",
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--no-install") {
+      opts.install = false;
+    } else if (arg === "--no-git") {
+      opts.git = false;
+    } else if (arg === "--no-python") {
+      opts.python = false;
+    } else if (arg === "--no-node") {
+      opts.node = false;
+    } else if (arg === "--db") {
+      i++;
+      const val = args[i];
+      if (val !== "postgres" && val !== "sqlite") {
+        console.error(`Error: --db must be "postgres" or "sqlite", got "${val}".`);
+        process.exit(1);
+      }
+      opts.db = val;
+    } else if (arg === "-h" || arg === "--help") {
+      opts.help = true;
+    } else if (arg.startsWith("-")) {
+      console.error(`Error: Unknown flag "${arg}". Use --help for usage.`);
+      process.exit(1);
+    } else if (!opts.name) {
+      opts.name = arg;
+    } else {
+      console.error(`Error: Unexpected argument "${arg}". Only one project name allowed.`);
+      process.exit(1);
+    }
+  }
+
+  return opts;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  const opts = parseArgs(process.argv);
+
+  if (opts.help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!opts.name) {
+    console.error("Error: Please provide a project name.\n");
+    printUsage();
+    process.exit(1);
+  }
+
+  const validation = validateProjectName(opts.name);
+  if (!validation.valid) {
+    console.error(`Error: ${validation.reason}`);
+    process.exit(1);
+  }
+
+  const projectDir = resolve(process.cwd(), opts.name);
+
+  if (dirExists(projectDir) && readdirSync(projectDir).length > 0) {
+    console.error(`Error: Directory "${opts.name}" already exists and is not empty.`);
+    process.exit(1);
+  }
+
+  // Locate templates directory (bundled inside the npm package).
+  const templatesDir = join(__dirname, "..", "templates", "fullstack");
+  if (!existsSync(templatesDir)) {
+    console.error(
+      `Error: Templates directory not found at "${templatesDir}".\n` +
+        "This is a packaging issue — please report it.",
+    );
+    process.exit(1);
+  }
+
+  console.log(`\n🚀 Creating project "${opts.name}" in ${projectDir}\n`);
+
+  // Placeholder replacements applied to every text file in the template.
+  const replacements = {
+    "{{PROJECT_NAME}}": opts.name,
+  };
+
+  copyDir(templatesDir, projectDir, replacements);
+
+  // Write .env / .env.example
+  writeEnvFiles(projectDir, opts.db, opts.name);
+
+  console.log("✅ Project files created.");
+
+  // ---- Optional: git init ----
+  if (opts.git) {
+    try {
+      execSync("git init", { cwd: projectDir, stdio: "ignore" });
+      console.log("✅ Initialized git repository.");
+    } catch {
+      console.warn("⚠️  Could not run git init. Skipping.");
+    }
+  }
+
+  // ---- Optional: install deps ----
+  if (opts.install) {
+    if (opts.python && existsSync(join(projectDir, "backend"))) {
+      console.log("📦 Installing Python dependencies (uv sync)...");
+      try {
+        execSync("uv sync", { cwd: join(projectDir, "backend"), stdio: "inherit" });
+        console.log("✅ Python dependencies installed.");
+      } catch {
+        console.warn("⚠️  uv sync failed. You can run it manually later.");
+      }
+    }
+
+    if (opts.node && existsSync(join(projectDir, "web"))) {
+      console.log("📦 Installing Node dependencies (npm install)...");
+      try {
+        execSync("npm install", { cwd: join(projectDir, "web"), stdio: "inherit" });
+        console.log("✅ Node dependencies installed.");
+      } catch {
+        console.warn("⚠️  npm install failed. You can run it manually later.");
+      }
+    }
+  }
+
+  // ---- Success ----
+  console.log(`
+🎉 Done! Your project is ready.
+
+Next steps:
+
+  cd ${opts.name}
+
+  # Start the backend
+  cd backend && uv run uvicorn app.main:app --reload
+
+  # Start the frontend (in another terminal)
+  cd web && npm run dev
+
+  # Open http://localhost:5173
+
+Happy hacking! 🏴‍☠️
+`);
+}
+
+main();

package/lib/scaffold.js

@@ -0,0 +1,144 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Validate that a project name contains only alphanumeric chars, hyphens,
+ * and underscores, starts with a letter or underscore, and is 1-214 chars.
+ * @param {string} name
+ * @returns {{ valid: boolean, reason?: string }}
+ */
+export function validateProjectName(name) {
+  if (!name) {
+    return { valid: false, reason: "Project name is required." };
+  }
+  if (name.length > 214) {
+    return { valid: false, reason: "Project name must be 214 characters or fewer." };
+  }
+  if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(name)) {
+    return {
+      valid: false,
+      reason:
+        "Project name must start with a letter or underscore and contain only alphanumeric characters, hyphens, and underscores.",
+    };
+  }
+  return { valid: true };
+}
+
+/**
+ * Generate a cryptographically random hex secret.
+ * @param {number} [bytes=32]
+ * @returns {string}
+ */
+export function generateSecret(bytes = 32) {
+  return randomBytes(bytes).toString("hex");
+}
+
+// Binary file extensions that should be copied without placeholder replacement.
+const BINARY_EXTENSIONS = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".ico", ".svg",
+  ".woff", ".woff2", ".ttf", ".eot",
+  ".zip", ".gz", ".tar", ".bz2",
+  ".pdf", ".mp3", ".mp4", ".webm",
+  ".wasm", ".bin",
+]);
+
+/**
+ * Recursively copy a directory, replacing placeholder strings in text files.
+ * @param {string} src  - source directory
+ * @param {string} dest - destination directory
+ * @param {Record<string, string>} replacements - map of placeholder -> value
+ */
+export function copyDir(src, dest, replacements) {
+  mkdirSync(dest, { recursive: true });
+
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      copyDir(srcPath, destPath, replacements);
+    } else {
+      const dotIdx = entry.lastIndexOf(".");
+      const ext = dotIdx > 0 ? entry.slice(dotIdx).toLowerCase() : "";
+      if (BINARY_EXTENSIONS.has(ext)) {
+        writeFileSync(destPath, readFileSync(srcPath));
+      } else {
+        let content = readFileSync(srcPath, "utf8");
+        for (const [placeholder, value] of Object.entries(replacements)) {
+          content = content.replaceAll(placeholder, value);
+        }
+        writeFileSync(destPath, content, "utf8");
+      }
+    }
+  }
+}
+
+/**
+ * Build the contents of a .env file.
+ * @param {"postgres" | "sqlite"} dbType
+ * @param {string} projectName
+ * @returns {string}
+ */
+function buildEnvContent(dbType, projectName) {
+  const signingKey = generateSecret();
+  const dbUrl =
+    dbType === "sqlite"
+      ? `sqlite+aiosqlite:///./data/${projectName}.db`
+      : `postgresql+psycopg://postgres:postgres@localhost:5432/${projectName}`;
+
+  return [
+    "# h4ckath0n environment",
+    "H4CKATH0N_ENV=development",
+    `H4CKATH0N_DATABASE_URL=${dbUrl}`,
+    `H4CKATH0N_AUTH_SIGNING_KEY=${signingKey}`,
+    "H4CKATH0N_RP_ID=localhost",
+    "H4CKATH0N_ORIGIN=http://localhost:5173",
+    "VITE_API_BASE_URL=/api",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Build the contents of a .env.example file.
+ * @param {"postgres" | "sqlite"} dbType
+ * @returns {string}
+ */
+function buildEnvExampleContent(dbType) {
+  const dbPlaceholder =
+    dbType === "sqlite"
+      ? "sqlite+aiosqlite:///./data/myproject.db"
+      : "postgresql+psycopg://postgres:postgres@localhost:5432/myproject";
+
+  return [
+    "# h4ckath0n environment",
+    "H4CKATH0N_ENV=development",
+    `H4CKATH0N_DATABASE_URL=${dbPlaceholder}`,
+    "H4CKATH0N_AUTH_SIGNING_KEY=<random-hex-secret>",
+    "H4CKATH0N_RP_ID=localhost",
+    "H4CKATH0N_ORIGIN=http://localhost:5173",
+    "VITE_API_BASE_URL=/api",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Write .env and .env.example into the destination directory.
+ * @param {string} dest - project root directory
+ * @param {"postgres" | "sqlite"} dbType
+ * @param {string} projectName
+ */
+export function writeEnvFiles(dest, dbType, projectName) {
+  writeFileSync(join(dest, ".env"), buildEnvContent(dbType, projectName), "utf8");
+  writeFileSync(join(dest, ".env.example"), buildEnvExampleContent(dbType), "utf8");
+}
+
+/**
+ * Check whether a directory already exists and is non-empty.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+export function dirExists(dir) {
+  return existsSync(dir) && statSync(dir).isDirectory();
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "h4ckath0n",
+  "version": "0.1.0",
+  "description": "Create a full-stack hackathon project with passkeys and strong defaults",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "h4ckath0n": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BTreeMap/h4ckath0n.git",
+    "directory": "packages/create-h4ckath0n"
+  },
+  "homepage": "https://github.com/BTreeMap/h4ckath0n",
+  "bugs": {
+    "url": "https://github.com/BTreeMap/h4ckath0n/issues"
+  },
+  "keywords": [
+    "hackathon",
+    "fullstack",
+    "passkeys",
+    "webauthn",
+    "react",
+    "fastapi"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/fullstack/README.md

@@ -0,0 +1,56 @@
+# {{PROJECT_NAME}}
+
+Full-stack hackathon project scaffolded with [h4ckath0n](https://github.com/BTreeMap/h4ckath0n).
+
+## Quick start
+
+```bash
+# Start both backend and frontend
+cd backend
+uv run h4ckath0n dev
+```
+
+Backend runs at http://localhost:8000, frontend at http://localhost:5173.
+
+## Structure
+
+```
+{{PROJECT_NAME}}/
+  backend/    Python (FastAPI + h4ckath0n library)
+  web/        React + Vite + TypeScript + Tailwind v4
+  .env        Environment variables (gitignored)
+```
+
+## Auth model
+
+- Passkeys (WebAuthn) for registration and login
+- Each device gets a P-256 keypair (private key non-extractable, stored in IndexedDB)
+- API requests use short-lived JWTs (15 min) signed by the device key
+- Server verifies JWT signature and enforces RBAC from the database
+- No privilege claims in the JWT; all roles/scopes are server-derived
+
+## Development
+
+### Backend
+
+```bash
+cd backend
+uv sync
+uv run uvicorn app.main:app --reload
+```
+
+### Frontend
+
+```bash
+cd web
+npm install
+npm run dev
+```
+
+### Environment
+
+Copy `.env.example` to `.env` and set values as needed. See the h4ckath0n docs for all configuration options.
+
+## License
+
+MIT

package/templates/fullstack/backend/.python-version

@@ -0,0 +1 @@
+3.14

package/templates/fullstack/backend/app/__init__.py

@@ -0,0 +1 @@
+"""Backend application package."""

package/templates/fullstack/backend/app/cli.py

@@ -0,0 +1,98 @@
+"""CLI for the scaffolded h4ckath0n project."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+
+def main() -> None:
+    """Entry point for the h4ckath0n CLI."""
+    if len(sys.argv) < 2:
+        _print_help()
+        return
+
+    command = sys.argv[1]
+    handlers = {
+        "dev": _cmd_dev,
+        "help": _print_help,
+    }
+
+    handler = handlers.get(command)
+    if handler:
+        handler()
+    else:
+        print(f"Unknown command: {command}")
+        _print_help()
+        sys.exit(1)
+
+
+def _cmd_dev() -> None:
+    """Run backend and frontend dev servers concurrently."""
+    project_root = _find_project_root()
+    backend_dir = os.path.join(project_root, "backend")
+    web_dir = os.path.join(project_root, "web")
+
+    print("Starting h4ckath0n dev servers...")
+    print(f"  Backend: http://localhost:8000 (from {backend_dir})")
+    print(f"  Frontend: http://localhost:5173 (from {web_dir})")
+    print()
+
+    processes = []
+    try:
+        # Start backend
+        backend_proc = subprocess.Popen(
+            [sys.executable, "-m", "uvicorn", "app.main:app", "--reload", "--port", "8000"],
+            cwd=backend_dir,
+        )
+        processes.append(backend_proc)
+
+        # Start frontend
+        npm_cmd = "npm.cmd" if sys.platform == "win32" else "npm"
+        frontend_proc = subprocess.Popen(
+            [npm_cmd, "run", "dev"],
+            cwd=web_dir,
+        )
+        processes.append(frontend_proc)
+
+        # Wait for any process to exit
+        for proc in processes:
+            proc.wait()
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    finally:
+        for proc in processes:
+            try:
+                proc.terminate()
+                proc.wait(timeout=5)
+            except (subprocess.TimeoutExpired, OSError):
+                proc.kill()
+
+
+def _find_project_root() -> str:
+    """Find the project root by looking for backend/ and web/ directories."""
+    # Start from the current working directory
+    cwd = os.getcwd()
+    if os.path.isdir(os.path.join(cwd, "backend")) and os.path.isdir(os.path.join(cwd, "web")):
+        return cwd
+    # Try parent of backend/
+    parent = os.path.dirname(cwd)
+    if os.path.isdir(os.path.join(parent, "backend")) and os.path.isdir(
+        os.path.join(parent, "web")
+    ):
+        return parent
+    # Default to cwd
+    return cwd
+
+
+def _print_help() -> None:
+    """Print CLI help."""
+    print("h4ckath0n backend CLI")
+    print()
+    print("Usage: uv run h4ckath0n <command>")
+    print("  (run from the backend/ directory of your scaffolded project)")
+    print()
+    print("Commands:")
+    print("  dev     Start backend and frontend dev servers")
+    print("  help    Show this help message")

package/templates/fullstack/backend/app/main.py

@@ -0,0 +1,7 @@
+"""Application entry point."""
+
+from app.middleware import add_csp_middleware
+from h4ckath0n import create_app
+
+app = create_app()
+add_csp_middleware(app)

package/templates/fullstack/backend/app/middleware.py

@@ -0,0 +1,55 @@
+"""Security middleware: CSP headers and device JWT verification."""
+
+from __future__ import annotations
+
+import os
+
+from fastapi import FastAPI
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+ENV_VAR = "H4CKATH0N_ENV"
+
+
+def add_csp_middleware(app: FastAPI) -> None:
+    """Add Content-Security-Policy middleware to the FastAPI app."""
+    app.add_middleware(CSPMiddleware)
+
+
+class CSPMiddleware(BaseHTTPMiddleware):
+    """Set Content-Security-Policy headers based on environment."""
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        response = await call_next(request)
+        env = os.getenv(ENV_VAR, "development")
+        if env == "production":
+            csp = (
+                "default-src 'self'; "
+                "script-src 'self'; "
+                "style-src 'self'; "
+                "img-src 'self' data:; "
+                "font-src 'self'; "
+                "connect-src 'self'; "
+                "frame-ancestors 'none'; "
+                "base-uri 'self'; "
+                "form-action 'self'"
+            )
+        else:
+            # Development: allow Vite dev server
+            csp = (
+                "default-src 'self' http://localhost:*; "
+                "script-src 'self' http://localhost:*; "
+                "style-src 'self' 'unsafe-inline' http://localhost:*; "
+                "img-src 'self' data: http://localhost:*; "
+                "font-src 'self' http://localhost:*; "
+                "connect-src 'self' http://localhost:* ws://localhost:*; "
+                "frame-ancestors 'none'; "
+                "base-uri 'self'; "
+                "form-action 'self'"
+            )
+        response.headers["Content-Security-Policy"] = csp
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        return response

package/templates/fullstack/backend/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "{{PROJECT_NAME}}-backend"
+version = "0.1.0"
+description = "Backend for {{PROJECT_NAME}}"
+requires-python = ">=3.11"
+dependencies = [
+    "h4ckath0n>=0.1.0",
+    "cryptography>=44.0",
+]
+
+[project.scripts]
+h4ckath0n = "app.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]

package/templates/fullstack/web/eslint.config.js

@@ -0,0 +1,22 @@
+import js from "@eslint/js";
+import globals from "globals";
+import reactHooks from "eslint-plugin-react-hooks";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  { ignores: ["dist"] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ["**/*.{ts,tsx}"],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      "react-hooks": reactHooks,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+    },
+  }
+);

package/templates/fullstack/web/index.html

@@ -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>{{PROJECT_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>