@basicbenframework/core 0.1.0

package/my-test-app/src/controllers/ProfileController.js

@@ -0,0 +1,66 @@
+import { validate, rules } from '@basicbenframework/core/validation'
+import { User } from '../models/User.js'
+import { createHash } from 'node:crypto'
+
+function hashPassword(password) {
+  return createHash('sha256').update(password).digest('hex')
+}
+
+export const ProfileController = {
+  async show(req, res) {
+    const user = await User.find(req.userId)
+    if (!user) {
+      return res.json({ error: 'User not found' }, 404)
+    }
+    res.json({
+      user: { id: user.id, name: user.name, email: user.email, created_at: user.created_at }
+    })
+  },
+
+  async update(req, res) {
+    const result = await validate(req.body, {
+      name: [rules.required, rules.string, rules.min(2)],
+      email: [rules.required, rules.email]
+    })
+
+    if (result.fails()) {
+      return res.json({ errors: result.errors }, 422)
+    }
+
+    const { name, email } = req.body
+    const user = await User.find(req.userId)
+
+    if (email !== user.email) {
+      const existing = await User.findByEmail(email)
+      if (existing) {
+        return res.json({ error: 'Email already taken' }, 400)
+      }
+    }
+
+    const updated = await User.update(req.userId, { name, email })
+    res.json({
+      user: { id: updated.id, name: updated.name, email: updated.email }
+    })
+  },
+
+  async changePassword(req, res) {
+    const result = await validate(req.body, {
+      currentPassword: [rules.required],
+      newPassword: [rules.required, rules.min(8)]
+    })
+
+    if (result.fails()) {
+      return res.json({ errors: result.errors }, 422)
+    }
+
+    const { currentPassword, newPassword } = req.body
+    const user = await User.find(req.userId)
+
+    if (user.password !== hashPassword(currentPassword)) {
+      return res.json({ error: 'Current password is incorrect' }, 400)
+    }
+
+    await User.update(req.userId, { password: hashPassword(newPassword) })
+    res.json({ message: 'Password updated successfully' })
+  }
+}

package/my-test-app/src/helpers/api.js

@@ -0,0 +1,24 @@
+export const api = async (path, options = {}) => {
+  const token = localStorage.getItem('token')
+  let res
+  try {
+    res = await fetch(path, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        ...options.headers
+      }
+    })
+  } catch {
+    throw new Error('Unable to connect to server')
+  }
+  let data
+  try {
+    data = await res.json()
+  } catch {
+    throw new Error(res.ok ? 'Invalid response from server' : `Server error (${res.status})`)
+  }
+  if (!res.ok) throw new Error(data.error || Object.values(data.errors || {})[0]?.[0] || 'Request failed')
+  return data
+}

package/my-test-app/src/main.jsx

@@ -0,0 +1,9 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './routes/App.jsx'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+)

package/my-test-app/src/middleware/auth.js

@@ -0,0 +1,16 @@
+import { verifyJwt } from '@basicbenframework/core/auth'
+
+export const auth = async (req, res, next) => {
+  const token = req.headers.authorization?.replace('Bearer ', '')
+  if (!token) {
+    return res.json({ error: 'Unauthorized' }, 401)
+  }
+
+  const payload = verifyJwt(token, process.env.APP_KEY)
+  if (!payload) {
+    return res.json({ error: 'Invalid token' }, 401)
+  }
+
+  req.userId = payload.userId
+  next()
+}

package/my-test-app/src/models/Post.js

@@ -0,0 +1,63 @@
+import { getDb } from '@basicbenframework/core/db'
+
+export const Post = {
+  async all() {
+    const db = await getDb()
+    return db.all('SELECT * FROM posts ORDER BY created_at DESC')
+  },
+
+  async find(id) {
+    const db = await getDb()
+    return db.get('SELECT * FROM posts WHERE id = ?', [id])
+  },
+
+  async findByUser(userId) {
+    const db = await getDb()
+    return db.all('SELECT * FROM posts WHERE user_id = ? ORDER BY created_at DESC', [userId])
+  },
+
+  async findPublished() {
+    const db = await getDb()
+    return db.all(`
+      SELECT posts.*, users.name as author_name
+      FROM posts
+      JOIN users ON posts.user_id = users.id
+      WHERE posts.published = 1
+      ORDER BY posts.created_at DESC
+    `)
+  },
+
+  async findPublishedById(id) {
+    const db = await getDb()
+    return db.get(`
+      SELECT posts.*, users.name as author_name
+      FROM posts
+      JOIN users ON posts.user_id = users.id
+      WHERE posts.id = ? AND posts.published = 1
+    `, [id])
+  },
+
+  async create(data) {
+    const db = await getDb()
+    const result = await db.run(
+      'INSERT INTO posts (user_id, title, content, published) VALUES (?, ?, ?, ?)',
+      [data.user_id, data.title, data.content, data.published ? 1 : 0]
+    )
+    return { id: result.lastInsertRowid, ...data }
+  },
+
+  async update(id, data) {
+    const db = await getDb()
+    const fields = Object.keys(data).map(k => `${k} = ?`).join(', ')
+    await db.run(
+      `UPDATE posts SET ${fields}, updated_at = CURRENT_TIMESTAMP WHERE id = ?`,
+      [...Object.values(data), id]
+    )
+    return this.find(id)
+  },
+
+  async delete(id) {
+    const db = await getDb()
+    return db.run('DELETE FROM posts WHERE id = ?', [id])
+  }
+}

package/my-test-app/src/models/User.js

@@ -0,0 +1,42 @@
+import { getDb } from '@basicbenframework/core/db'
+
+export const User = {
+  async all() {
+    const db = await getDb()
+    return db.all('SELECT * FROM users')
+  },
+
+  async find(id) {
+    const db = await getDb()
+    return db.get('SELECT * FROM users WHERE id = ?', [id])
+  },
+
+  async findByEmail(email) {
+    const db = await getDb()
+    return db.get('SELECT * FROM users WHERE email = ?', [email])
+  },
+
+  async create(data) {
+    const db = await getDb()
+    const result = await db.run(
+      'INSERT INTO users (name, email, password) VALUES (?, ?, ?)',
+      [data.name, data.email, data.password]
+    )
+    return { id: result.lastInsertRowid, ...data }
+  },
+
+  async update(id, data) {
+    const db = await getDb()
+    const fields = Object.keys(data).map(k => `${k} = ?`).join(', ')
+    await db.run(
+      `UPDATE users SET ${fields} WHERE id = ?`,
+      [...Object.values(data), id]
+    )
+    return this.find(id)
+  },
+
+  async delete(id) {
+    const db = await getDb()
+    return db.run('DELETE FROM users WHERE id = ?', [id])
+  }
+}

package/my-test-app/src/routes/App.jsx

@@ -0,0 +1,38 @@
+import { createClientApp } from '@basicbenframework/core/client'
+import { AppLayout } from '../client/layouts/AppLayout'
+import { AuthLayout } from '../client/layouts/AuthLayout'
+import { DocsLayout } from '../client/layouts/DocsLayout'
+import { Home } from '../client/pages/Home'
+import { Auth } from '../client/pages/Auth'
+import { Feed } from '../client/pages/Feed'
+import { FeedPost } from '../client/pages/FeedPost'
+import { Posts } from '../client/pages/Posts'
+import { PostForm } from '../client/pages/PostForm'
+import { Profile } from '../client/pages/Profile'
+import { GettingStarted } from '../client/pages/GettingStarted'
+import { Database } from '../client/pages/Database'
+import { Routing } from '../client/pages/Routing'
+import { Authentication } from '../client/pages/Authentication'
+import { Validation } from '../client/pages/Validation'
+import { Testing } from '../client/pages/Testing'
+
+export default createClientApp({
+  layout: AppLayout,
+  routes: {
+    '/': Home,
+    '/login': { component: Auth, layout: AuthLayout, guest: true },
+    '/register': { component: Auth, layout: AuthLayout, guest: true },
+    '/feed': Feed,
+    '/feed/:id': FeedPost,
+    '/posts': { component: Posts, auth: true },
+    '/posts/new': { component: PostForm, auth: true },
+    '/posts/:id/edit': { component: PostForm, auth: true },
+    '/profile': { component: Profile, auth: true },
+    '/docs': { component: GettingStarted, layout: DocsLayout },
+    '/docs/routing': { component: Routing, layout: DocsLayout },
+    '/docs/database': { component: Database, layout: DocsLayout },
+    '/docs/authentication': { component: Authentication, layout: DocsLayout },
+    '/docs/validation': { component: Validation, layout: DocsLayout },
+    '/docs/testing': { component: Testing, layout: DocsLayout },
+  }
+})

package/my-test-app/src/routes/api/auth.js

@@ -0,0 +1,7 @@
+import { AuthController } from '../../controllers/AuthController.js'
+
+export default (router) => {
+  router.post('/api/auth/register', AuthController.register)
+  router.post('/api/auth/login', AuthController.login)
+  router.get('/api/user', AuthController.user)
+}

package/my-test-app/src/routes/api/posts.js

@@ -0,0 +1,15 @@
+import { PostController } from '../../controllers/PostController.js'
+import { auth } from '../../middleware/auth.js'
+
+export default (router) => {
+  // Public feed routes
+  router.get('/api/feed', PostController.feed)
+  router.get('/api/feed/:id', PostController.feedShow)
+
+  // Authenticated post routes
+  router.get('/api/posts', auth, PostController.index)
+  router.post('/api/posts', auth, PostController.store)
+  router.get('/api/posts/:id', auth, PostController.show)
+  router.put('/api/posts/:id', auth, PostController.update)
+  router.delete('/api/posts/:id', auth, PostController.destroy)
+}

package/my-test-app/src/routes/api/profile.js

@@ -0,0 +1,8 @@
+import { ProfileController } from '../../controllers/ProfileController.js'
+import { auth } from '../../middleware/auth.js'
+
+export default (router) => {
+  router.get('/api/profile', auth, ProfileController.show)
+  router.put('/api/profile', auth, ProfileController.update)
+  router.put('/api/profile/password', auth, ProfileController.changePassword)
+}

package/my-test-app/src/server/index.js

@@ -0,0 +1,16 @@
+/**
+ * Server entry point (optional)
+ *
+ * Delete this file to use the default server.
+ * Customize here for websockets, custom middleware, etc.
+ */
+
+import { createServer } from '@basicbenframework/core/server'
+
+const app = await createServer()
+
+const port = process.env.PORT || 3001
+
+app.listen(port, () => {
+  console.log(`Server running at http://localhost:${port}`)
+})

package/my-test-app/vite.config.js

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: parseInt(process.env.VITE_PORT || 3000),
+    proxy: {
+      '/api': {
+        target: `http://localhost:${process.env.PORT || 3001}`,
+        changeOrigin: true
+      }
+    }
+  },
+  build: {
+    outDir: 'dist/client'
+  }
+})

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@basicbenframework/core",
+  "version": "0.1.0",
+  "description": "A full-stack framework for React. Minimal dependencies, maximum clarity.",
+  "author": "ctmakes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BasicBenFramework/basicben-framework.git"
+  },
+  "homepage": "https://github.com/BasicBenFramework/basicben-framework#readme",
+  "bugs": {
+    "url": "https://github.com/BasicBenFramework/basicben-framework/issues"
+  },
+  "type": "module",
+  "bin": {
+    "basicben": "./bin/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server/index.js",
+    "./client": "./src/client/index.js",
+    "./validation": "./src/validation/index.js",
+    "./auth": "./src/auth/jwt.js",
+    "./db": "./src/db/index.js"
+  },
+  "engines": {
+    "node": ">=24.14.0"
+  },
+  "scripts": {
+    "test": "node --test src/**/*.test.js",
+    "test:db": "node --test src/db/**/*.test.js",
+    "test:validation": "node --test src/validation/**/*.test.js",
+    "test:auth": "node --test src/auth/**/*.test.js",
+    "test:server": "node --test src/server/**/*.test.js",
+    "test:cli": "node --test src/cli/**/*.test.js",
+    "test:scaffolding": "node --test src/scaffolding/**/*.test.js",
+    "test:app": "./scripts/test-app.sh"
+  },
+  "keywords": [
+    "react",
+    "framework",
+    "fullstack",
+    "vite",
+    "minimal"
+  ],
+  "license": "MIT",
+  "dependencies": {},
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "vite": ">=7",
+    "@vitejs/plugin-react": ">=5"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": ">=12",
+    "pg": ">=8",
+    "@libsql/client": ">=0.17",
+    "@planetscale/database": ">=1",
+    "@neondatabase/serverless": ">=1.0"
+  }
+}

package/scripts/test-app.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# Test script for BasicBen framework
+# Deletes my-test-app, creates a fresh one, and runs migrations
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(dirname "$SCRIPT_DIR")"
+
+echo "=== BasicBen Test App Setup ==="
+echo ""
+
+# Step 1: Delete existing my-test-app
+if [ -d "$ROOT_DIR/my-test-app" ]; then
+  echo "Removing existing my-test-app..."
+  rm -rf "$ROOT_DIR/my-test-app"
+fi
+
+# Step 2: Create new test app with --local flag
+echo "Creating new test app..."
+cd "$ROOT_DIR"
+node create-basicben-app/index.js my-test-app --local
+
+# Step 3: Configure .env with port 3002 for frontend
+echo "Configuring .env..."
+APP_KEY=$(openssl rand -base64 32)
+cat > "$ROOT_DIR/my-test-app/.env" << EOF
+# Application
+APP_KEY=$APP_KEY
+
+# Server Ports
+PORT=3001              # API server
+VITE_PORT=3002         # Frontend dev server
+
+# Database
+DATABASE_URL=./database.sqlite
+EOF
+
+# Step 4: Install dependencies
+echo ""
+echo "Installing dependencies..."
+cd "$ROOT_DIR/my-test-app"
+npm install
+
+# Step 5: Run migrations
+echo ""
+echo "Running migrations..."
+npm run migrate
+
+echo ""
+echo "=== Setup Complete ==="
+echo ""
+echo "To start the dev server:"
+echo "  cd my-test-app"
+echo "  npm run dev"
+echo ""
+echo "Frontend: http://localhost:3002"
+echo "API:      http://localhost:3001"

package/src/auth/jwt.js

@@ -0,0 +1,195 @@
+/**
+ * Auth helpers using node:crypto.
+ * No jsonwebtoken or bcrypt dependencies needed.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+// Re-export password helpers
+export { hashPassword, verifyPassword, needsRehash } from './password.js'
+
+/**
+ * Sign a JWT token
+ *
+ * @param {Object} payload - Data to encode in the token
+ * @param {string} secret - Secret key for signing
+ * @param {Object} options - Options (expiresIn)
+ * @returns {string} - JWT token
+ *
+ * @example
+ * const token = signJwt({ userId: 1 }, process.env.APP_KEY, { expiresIn: '7d' })
+ */
+export function signJwt(payload, secret, options = {}) {
+  if (!secret) {
+    throw new Error('JWT secret is required')
+  }
+
+  const header = {
+    alg: 'HS256',
+    typ: 'JWT'
+  }
+
+  const now = Math.floor(Date.now() / 1000)
+
+  const tokenPayload = {
+    ...payload,
+    iat: now
+  }
+
+  // Handle expiration
+  if (options.expiresIn) {
+    tokenPayload.exp = now + parseExpiry(options.expiresIn)
+  }
+
+  const encodedHeader = base64UrlEncode(JSON.stringify(header))
+  const encodedPayload = base64UrlEncode(JSON.stringify(tokenPayload))
+
+  const signature = sign(`${encodedHeader}.${encodedPayload}`, secret)
+
+  return `${encodedHeader}.${encodedPayload}.${signature}`
+}
+
+/**
+ * Verify and decode a JWT token
+ *
+ * @param {string} token - JWT token to verify
+ * @param {string} secret - Secret key used for signing
+ * @returns {Object|null} - Decoded payload or null if invalid
+ *
+ * @example
+ * const payload = verifyJwt(token, process.env.APP_KEY)
+ * if (!payload) {
+ *   // Invalid or expired token
+ * }
+ */
+export function verifyJwt(token, secret) {
+  if (!token || !secret) {
+    return null
+  }
+
+  const parts = token.split('.')
+  if (parts.length !== 3) {
+    return null
+  }
+
+  const [encodedHeader, encodedPayload, signature] = parts
+
+  // Verify signature
+  const expectedSignature = sign(`${encodedHeader}.${encodedPayload}`, secret)
+
+  if (!safeCompare(signature, expectedSignature)) {
+    return null
+  }
+
+  // Decode payload
+  try {
+    const payload = JSON.parse(base64UrlDecode(encodedPayload))
+
+    // Check expiration
+    if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
+      return null
+    }
+
+    return payload
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Decode a JWT token without verification
+ * Useful for debugging or reading claims before verification
+ *
+ * @param {string} token - JWT token
+ * @returns {Object|null} - Decoded payload or null if malformed
+ */
+export function decodeJwt(token) {
+  if (!token) return null
+
+  const parts = token.split('.')
+  if (parts.length !== 3) return null
+
+  try {
+    return JSON.parse(base64UrlDecode(parts[1]))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Create HMAC-SHA256 signature
+ */
+function sign(data, secret) {
+  return base64UrlEncode(
+    createHmac('sha256', secret).update(data).digest()
+  )
+}
+
+/**
+ * Base64URL encode (URL-safe base64)
+ */
+function base64UrlEncode(data) {
+  const base64 = Buffer.isBuffer(data)
+    ? data.toString('base64')
+    : Buffer.from(data).toString('base64')
+
+  return base64
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+}
+
+/**
+ * Base64URL decode
+ */
+function base64UrlDecode(str) {
+  // Add padding if needed
+  const pad = str.length % 4
+  const padded = pad ? str + '='.repeat(4 - pad) : str
+
+  // Convert URL-safe chars back
+  const base64 = padded.replace(/-/g, '+').replace(/_/g, '/')
+
+  return Buffer.from(base64, 'base64').toString('utf8')
+}
+
+/**
+ * Timing-safe string comparison
+ */
+function safeCompare(a, b) {
+  if (a.length !== b.length) {
+    return false
+  }
+
+  const bufA = Buffer.from(a)
+  const bufB = Buffer.from(b)
+
+  return timingSafeEqual(bufA, bufB)
+}
+
+/**
+ * Parse expiry string to seconds
+ * Supports: 60 (seconds), '60s', '5m', '2h', '7d'
+ */
+function parseExpiry(expiry) {
+  if (typeof expiry === 'number') {
+    return expiry
+  }
+
+  const match = expiry.match(/^(\d+)(s|m|h|d)?$/)
+  if (!match) {
+    throw new Error(`Invalid expiry format: ${expiry}`)
+  }
+
+  const value = parseInt(match[1], 10)
+  const unit = match[2] || 's'
+
+  const multipliers = {
+    s: 1,
+    m: 60,
+    h: 60 * 60,
+    d: 60 * 60 * 24
+  }
+
+  return value * multipliers[unit]
+}