@basicbenframework/core 0.1.0

package/src/auth/password.js

@@ -0,0 +1,132 @@
+/**
+ * Secure password hashing using node:crypto scrypt.
+ *
+ * Comparable to bcrypt/Argon2 used by Laravel and Next.js.
+ * - Deliberately slow (configurable cost)
+ * - Automatic random salt
+ * - Timing-safe comparison
+ */
+
+import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto'
+import { promisify } from 'node:util'
+
+const scryptAsync = promisify(scrypt)
+
+// Default parameters (similar to bcrypt cost factor 10)
+const DEFAULT_KEY_LENGTH = 64
+const DEFAULT_COST = 16384  // N - CPU/memory cost (2^14)
+const DEFAULT_BLOCK_SIZE = 8  // r
+const DEFAULT_PARALLELIZATION = 1  // p
+const SALT_LENGTH = 16
+
+/**
+ * Hash a password securely
+ *
+ * @param {string} password - Plain text password
+ * @param {Object} options - Optional parameters
+ * @returns {Promise<string>} - Hash in format: salt:hash:params
+ *
+ * @example
+ * const hash = await hashPassword('mysecretpassword')
+ * // Store hash in database
+ */
+export async function hashPassword(password, options = {}) {
+  const {
+    keyLength = DEFAULT_KEY_LENGTH,
+    cost = DEFAULT_COST,
+    blockSize = DEFAULT_BLOCK_SIZE,
+    parallelization = DEFAULT_PARALLELIZATION
+  } = options
+
+  const salt = randomBytes(SALT_LENGTH)
+
+  const derivedKey = await scryptAsync(password, salt, keyLength, {
+    N: cost,
+    r: blockSize,
+    p: parallelization
+  })
+
+  // Format: base64(salt):base64(hash):N:r:p:keylen
+  const params = `${cost}:${blockSize}:${parallelization}:${keyLength}`
+  return `${salt.toString('base64')}:${derivedKey.toString('base64')}:${params}`
+}
+
+/**
+ * Verify a password against a hash
+ *
+ * @param {string} password - Plain text password to verify
+ * @param {string} hash - Stored hash from hashPassword()
+ * @returns {Promise<boolean>} - True if password matches
+ *
+ * @example
+ * const isValid = await verifyPassword('mysecretpassword', storedHash)
+ * if (!isValid) {
+ *   // Invalid password
+ * }
+ */
+export async function verifyPassword(password, hash) {
+  if (!password || !hash) {
+    return false
+  }
+
+  try {
+    const parts = hash.split(':')
+    if (parts.length !== 6) {
+      return false
+    }
+
+    const [saltB64, hashB64, costStr, blockSizeStr, parallelizationStr, keyLengthStr] = parts
+
+    const salt = Buffer.from(saltB64, 'base64')
+    const storedHash = Buffer.from(hashB64, 'base64')
+    const cost = parseInt(costStr, 10)
+    const blockSize = parseInt(blockSizeStr, 10)
+    const parallelization = parseInt(parallelizationStr, 10)
+    const keyLength = parseInt(keyLengthStr, 10)
+
+    const derivedKey = await scryptAsync(password, salt, keyLength, {
+      N: cost,
+      r: blockSize,
+      p: parallelization
+    })
+
+    // Timing-safe comparison to prevent timing attacks
+    return timingSafeEqual(storedHash, derivedKey)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Check if a hash needs to be rehashed (e.g., cost factor increased)
+ *
+ * @param {string} hash - Stored hash
+ * @param {Object} options - Current desired parameters
+ * @returns {boolean} - True if hash should be regenerated
+ */
+export function needsRehash(hash, options = {}) {
+  const {
+    cost = DEFAULT_COST,
+    blockSize = DEFAULT_BLOCK_SIZE,
+    parallelization = DEFAULT_PARALLELIZATION,
+    keyLength = DEFAULT_KEY_LENGTH
+  } = options
+
+  try {
+    const parts = hash.split(':')
+    if (parts.length !== 6) {
+      return true
+    }
+
+    const [, , costStr, blockSizeStr, parallelizationStr, keyLengthStr] = parts
+
+    return (
+      parseInt(costStr, 10) !== cost ||
+      parseInt(blockSizeStr, 10) !== blockSize ||
+      parseInt(parallelizationStr, 10) !== parallelization ||
+      parseInt(keyLengthStr, 10) !== keyLength
+    )
+  } catch {
+    return true
+  }
+}

package/src/cli/colors.js

@@ -0,0 +1,31 @@
+/**
+ * Simple ANSI color helpers. No Chalk needed.
+ */
+
+const isColorSupported = process.stdout.isTTY && !process.env.NO_COLOR
+
+const code = (open, close) => {
+  if (!isColorSupported) return (str) => str
+  return (str) => `\x1b[${open}m${str}\x1b[${close}m`
+}
+
+export const bold = code(1, 22)
+export const dim = code(2, 22)
+export const italic = code(3, 23)
+export const underline = code(4, 24)
+
+export const red = code(31, 39)
+export const green = code(32, 39)
+export const yellow = code(33, 39)
+export const blue = code(34, 39)
+export const magenta = code(35, 39)
+export const cyan = code(36, 39)
+export const white = code(37, 39)
+export const gray = code(90, 39)
+
+// Semantic aliases
+export const success = green
+export const error = red
+export const warn = yellow
+export const info = cyan
+export const muted = gray

package/src/cli/dispatcher.js

@@ -0,0 +1,168 @@
+/**
+ * Command dispatcher. Maps command names to handlers.
+ */
+
+import { bold, red, cyan, yellow, dim } from './colors.js'
+
+// Command registry
+const commands = {
+  // Development
+  dev: () => import('../commands/dev.js'),
+  build: () => import('../commands/build.js'),
+  start: () => import('../commands/start.js'),
+  test: () => import('../commands/test.js'),
+
+  // Scaffolding
+  'make:controller': () => import('../commands/make-controller.js'),
+  'make:model': () => import('../commands/make-model.js'),
+  'make:route': () => import('../commands/make-route.js'),
+  'make:migration': () => import('../commands/make-migration.js'),
+  'make:middleware': () => import('../commands/make-middleware.js'),
+
+  // Database
+  migrate: () => import('../commands/migrate.js'),
+  'migrate:rollback': () => import('../commands/migrate-rollback.js'),
+  'migrate:fresh': () => import('../commands/migrate-fresh.js'),
+  'migrate:status': () => import('../commands/migrate-status.js'),
+  'migrate:make': () => import('../commands/make-migration.js'), // alias
+
+  // Seeding
+  seed: () => import('../commands/seed.js'),
+  'db:seed': () => import('../commands/seed.js'), // alias
+  'make:seed': () => import('../commands/make-seed.js'),
+
+  // Help
+  help: () => import('../commands/help.js')
+}
+
+// Command metadata for help display
+export const commandMeta = {
+  dev: {
+    description: 'Start development server (Vite + Node with hot reload)',
+    usage: 'basicben dev',
+    options: {
+      '--port <port>': 'API server port (default: 3001)'
+    }
+  },
+  build: {
+    description: 'Build client and server for production',
+    usage: 'basicben build',
+    options: {
+      '--static': 'Build client only (for static hosts like CF Pages)'
+    }
+  },
+  start: {
+    description: 'Start production server',
+    usage: 'basicben start',
+    options: {
+      '--port <port>': 'Server port (default: 3000)'
+    }
+  },
+  test: {
+    description: 'Run tests with Vitest',
+    usage: 'basicben test [files]',
+    options: {
+      '--watch, -w': 'Watch mode (re-run on changes)',
+      '--coverage': 'Generate coverage report',
+      '--ui': 'Open Vitest UI'
+    }
+  },
+
+  'make:controller': {
+    description: 'Generate a controller with CRUD methods',
+    usage: 'basicben make:controller <Name>',
+    example: 'basicben make:controller User'
+  },
+  'make:model': {
+    description: 'Generate a model with common database methods',
+    usage: 'basicben make:model <Name>',
+    example: 'basicben make:model User'
+  },
+  'make:route': {
+    description: 'Generate a route file with REST endpoints',
+    usage: 'basicben make:route <name>',
+    example: 'basicben make:route users'
+  },
+  'make:migration': {
+    description: 'Generate a timestamped migration file',
+    usage: 'basicben make:migration <name>',
+    example: 'basicben make:migration create_users_table'
+  },
+  'make:middleware': {
+    description: 'Generate middleware (includes auth template)',
+    usage: 'basicben make:middleware <name>',
+    example: 'basicben make:middleware auth'
+  },
+
+  migrate: {
+    description: 'Run all pending migrations',
+    usage: 'basicben migrate'
+  },
+  'migrate:rollback': {
+    description: 'Roll back the last migration batch',
+    usage: 'basicben migrate:rollback'
+  },
+  'migrate:fresh': {
+    description: 'Drop all tables and re-run all migrations',
+    usage: 'basicben migrate:fresh'
+  },
+  'migrate:status': {
+    description: 'Show which migrations have run',
+    usage: 'basicben migrate:status'
+  },
+
+  seed: {
+    description: 'Run database seeders',
+    usage: 'basicben seed [name]',
+    example: 'basicben seed users'
+  },
+  'make:seed': {
+    description: 'Generate a new seed file',
+    usage: 'basicben make:seed <name>',
+    example: 'basicben make:seed users'
+  },
+
+  help: {
+    description: 'Show help for a command',
+    usage: 'basicben help [command]'
+  }
+}
+
+export async function dispatch(command, args, flags) {
+  // Version flag (check first)
+  if (flags.version || flags.v) {
+    const pkg = await import('../../package.json', { with: { type: 'json' } })
+    console.log(pkg.default.version)
+    return
+  }
+
+  // No command or help flag
+  if (!command || flags.help || flags.h) {
+    const helpModule = await commands.help()
+    return helpModule.run(args, flags)
+  }
+
+  // Look up command
+  const loader = commands[command]
+
+  if (!loader) {
+    console.error(`\n${red('Error:')} Unknown command ${bold(command)}`)
+    console.error(`\nRun ${cyan('basicben help')} to see available commands.\n`)
+    process.exit(1)
+  }
+
+  try {
+    const module = await loader()
+    await module.run(args, flags)
+  } catch (err) {
+    // Handle module not found (command not implemented yet)
+    if (err.code === 'ERR_MODULE_NOT_FOUND') {
+      console.error(`\n${yellow('Not implemented:')} ${bold(command)}`)
+      console.error(`${dim('This command is coming soon.')}\n`)
+      process.exit(1)
+    }
+
+    // Re-throw other errors
+    throw err
+  }
+}

package/src/cli/parser.js

@@ -0,0 +1,91 @@
+/**
+ * Custom argument parser. No Commander.js needed.
+ *
+ * Handles:
+ * - Commands: basicben dev, basicben make:controller
+ * - Positional args: basicben make:controller UserController
+ * - Flags: --port=3000, --verbose, -v
+ */
+
+export function parseArgs(argv) {
+  const result = {
+    command: null,
+    args: [],
+    flags: {}
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+
+    // Long flag with value: --port=3000
+    if (arg.startsWith('--') && arg.includes('=')) {
+      const [key, value] = arg.slice(2).split('=')
+      result.flags[key] = value
+      continue
+    }
+
+    // Long flag: --verbose (boolean) or --port 3000 (with next arg)
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+      const next = argv[i + 1]
+
+      // If next arg exists and isn't a flag, use it as value
+      if (next && !next.startsWith('-')) {
+        result.flags[key] = next
+        i++ // skip next
+      } else {
+        result.flags[key] = true
+      }
+      continue
+    }
+
+    // Short flags: -v, -p 3000
+    if (arg.startsWith('-') && arg.length === 2) {
+      const key = arg.slice(1)
+      const next = argv[i + 1]
+
+      if (next && !next.startsWith('-')) {
+        result.flags[key] = next
+        i++
+      } else {
+        result.flags[key] = true
+      }
+      continue
+    }
+
+    // Combined short flags: -abc (multiple booleans)
+    if (arg.startsWith('-') && arg.length > 2) {
+      for (const char of arg.slice(1)) {
+        result.flags[char] = true
+      }
+      continue
+    }
+
+    // First non-flag is the command
+    if (!result.command) {
+      result.command = arg
+      continue
+    }
+
+    // Everything else is a positional arg
+    result.args.push(arg)
+  }
+
+  return result
+}
+
+/**
+ * Expand flag aliases to full names
+ */
+export function expandAliases(flags, aliases) {
+  const expanded = { ...flags }
+
+  for (const [short, long] of Object.entries(aliases)) {
+    if (expanded[short] !== undefined && expanded[long] === undefined) {
+      expanded[long] = expanded[short]
+      delete expanded[short]
+    }
+  }
+
+  return expanded
+}

package/src/client/context.js

@@ -0,0 +1,4 @@
+import { createContext } from 'react'
+
+export const RouterContext = createContext(null)
+export const AuthContext = createContext(null)

package/src/client/hooks.js

@@ -0,0 +1,50 @@
+import { useContext } from 'react'
+import { RouterContext, AuthContext } from './context.js'
+
+/**
+ * Access auth state and methods
+ * @returns {{ user: object|null, setUser: function, logout: function, loading: boolean }}
+ */
+export function useAuth() {
+  const context = useContext(AuthContext)
+  if (!context) {
+    throw new Error('useAuth must be used within createClientApp')
+  }
+  return context
+}
+
+/**
+ * Get navigation function
+ * @returns {function} navigate(path, options)
+ */
+export function useNavigate() {
+  const context = useContext(RouterContext)
+  if (!context) {
+    throw new Error('useNavigate must be used within createClientApp')
+  }
+  return context.navigate
+}
+
+/**
+ * Get current route params
+ * @returns {object} params object (e.g. { id: '123' })
+ */
+export function useParams() {
+  const context = useContext(RouterContext)
+  if (!context) {
+    throw new Error('useParams must be used within createClientApp')
+  }
+  return context.params
+}
+
+/**
+ * Get current path
+ * @returns {string} current pathname
+ */
+export function usePath() {
+  const context = useContext(RouterContext)
+  if (!context) {
+    throw new Error('usePath must be used within createClientApp')
+  }
+  return context.path
+}

package/src/client/index.js

@@ -0,0 +1,3 @@
+export { createClientApp } from './router.js'
+export { useAuth, useNavigate, useParams, usePath } from './hooks.js'
+export { RouterContext, AuthContext } from './context.js'

package/src/client/router.js

@@ -0,0 +1,184 @@
+import { useState, useEffect, useCallback, createElement } from 'react'
+import { RouterContext, AuthContext } from './context.js'
+
+/**
+ * Create a client-side React app with routing
+ *
+ * @param {object} config
+ * @param {object} config.routes - Route definitions { path: Component | { component, auth?, guest?, layout? } }
+ * @param {function} [config.layout] - Default layout wrapper
+ * @param {function} [config.api] - API function for auth check (default: fetch /api/user)
+ * @param {function} [config.Loading] - Loading component
+ * @returns {function} React component
+ */
+export function createClientApp(config) {
+  const { routes, layout: DefaultLayout, api, Loading } = config
+
+  // Normalize routes to consistent format
+  const normalizedRoutes = Object.entries(routes).map(([path, value]) => {
+    const isSimple = typeof value === 'function'
+    return {
+      path,
+      pattern: pathToRegex(path),
+      component: isSimple ? value : value.component,
+      auth: isSimple ? false : value.auth || false,
+      guest: isSimple ? false : value.guest || false,
+      layout: isSimple ? null : value.layout || null,
+    }
+  })
+
+  function App() {
+    const [user, setUser] = useState(null)
+    const [loading, setLoading] = useState(true)
+    const [path, setPath] = useState(window.location.pathname)
+
+    // Match current route
+    const matchRoute = useCallback((pathname) => {
+      for (const route of normalizedRoutes) {
+        const match = pathname.match(route.pattern)
+        if (match) {
+          const routeParams = extractParams(route.path, match)
+          return { route, params: routeParams }
+        }
+      }
+      return null
+    }, [])
+
+    // Navigate function
+    const navigate = useCallback((to, options = {}) => {
+      const { replace = false } = options
+
+      if (replace) {
+        window.history.replaceState({}, '', to)
+      } else {
+        window.history.pushState({}, '', to)
+      }
+
+      setPath(to)
+      window.scrollTo(0, 0)
+    }, [])
+
+    // Logout function
+    const logout = useCallback(() => {
+      localStorage.removeItem('token')
+      setUser(null)
+      navigate('/')
+    }, [navigate])
+
+    // Auth check on mount
+    useEffect(() => {
+      const token = localStorage.getItem('token')
+      if (!token) {
+        setLoading(false)
+        return
+      }
+
+      const checkAuth = api || defaultApi
+      checkAuth('/api/user')
+        .then(data => setUser(data.user))
+        .catch(() => localStorage.removeItem('token'))
+        .finally(() => setLoading(false))
+    }, [])
+
+    // Handle browser back/forward
+    useEffect(() => {
+      const handlePopState = () => {
+        setPath(window.location.pathname)
+      }
+      window.addEventListener('popstate', handlePopState)
+      return () => window.removeEventListener('popstate', handlePopState)
+    }, [])
+
+    // Loading state
+    if (loading) {
+      if (Loading) return createElement(Loading)
+      return createElement('div', {
+        style: { display: 'flex', justifyContent: 'center', alignItems: 'center', minHeight: '100vh' }
+      }, 'Loading...')
+    }
+
+    // Find matching route
+    const matched = matchRoute(path)
+    if (!matched) {
+      return createElement('div', null, '404 - Not Found')
+    }
+
+    const { route, params } = matched
+
+    // Route guards
+    if (route.auth && !user) {
+      navigate('/login', { replace: true })
+      return null
+    }
+    if (route.guest && user) {
+      navigate('/', { replace: true })
+      return null
+    }
+
+    // Build page element
+    let wrapped = createElement(route.component)
+
+    // Apply layout: route-specific layout replaces default, or use default
+    const Layout = route.layout || DefaultLayout
+    if (Layout) {
+      wrapped = createElement(Layout, null, wrapped)
+    }
+
+    // Provide context
+    return createElement(
+      AuthContext.Provider,
+      { value: { user, setUser, logout, loading } },
+      createElement(
+        RouterContext.Provider,
+        { value: { path, params, navigate } },
+        wrapped
+      )
+    )
+  }
+
+  return App
+}
+
+/**
+ * Convert route path to regex
+ * /posts/:id -> /^\/posts\/([^/]+)$/
+ */
+function pathToRegex(path) {
+  if (path === '*') return /^.*$/
+
+  const pattern = path
+    .replace(/\*/g, '.*')
+    .replace(/:(\w+)/g, '([^/]+)')
+    .replace(/\//g, '\\/')
+
+  return new RegExp(`^${pattern}$`)
+}
+
+/**
+ * Extract params from match
+ */
+function extractParams(path, match) {
+  const params = {}
+  const paramNames = path.match(/:(\w+)/g) || []
+
+  paramNames.forEach((name, i) => {
+    params[name.slice(1)] = match[i + 1]
+  })
+
+  return params
+}
+
+/**
+ * Default API function
+ */
+async function defaultApi(path) {
+  const token = localStorage.getItem('token')
+  const res = await fetch(path, {
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { Authorization: `Bearer ${token}` } : {})
+    }
+  })
+  if (!res.ok) throw new Error('Request failed')
+  return res.json()
+}