@basicbenframework/core 0.1.0

package/src/commands/migrate-fresh.js

@@ -0,0 +1,32 @@
+/**
+ * migrate:fresh command
+ * Drops all tables and re-runs all migrations
+ */
+
+import { createMigrator } from '../db/migrator.js'
+import { green, yellow, cyan, dim, red } from '../cli/colors.js'
+
+export async function run(args, flags) {
+  console.log(`\n${yellow('Dropping all tables...')}\n`)
+
+  try {
+    const migrator = await createMigrator()
+    const result = await migrator.fresh()
+
+    console.log(`${cyan('Running migrations...')}\n`)
+
+    if (result.ran.length === 0) {
+      console.log(`${yellow('No migrations to run.')}\n`)
+      return
+    }
+
+    for (const name of result.ran) {
+      console.log(`${green('✓')} ${name}`)
+    }
+
+    console.log(`\n${green('Fresh migration complete:')} ${result.ran.length} file(s)\n`)
+  } catch (err) {
+    console.error(`\n${red('Fresh migration failed:')}\n${err.message}\n`)
+    process.exit(1)
+  }
+}

package/src/commands/migrate-rollback.js

@@ -0,0 +1,30 @@
+/**
+ * migrate:rollback command
+ * Rolls back the last batch of migrations
+ */
+
+import { createMigrator } from '../db/migrator.js'
+import { green, yellow, cyan, dim, red } from '../cli/colors.js'
+
+export async function run(args, flags) {
+  console.log(`\n${cyan('Rolling back migrations...')}\n`)
+
+  try {
+    const migrator = await createMigrator()
+    const result = await migrator.rollback()
+
+    if (result.rolledBack.length === 0) {
+      console.log(`${yellow('Nothing to rollback.')}\n`)
+      return
+    }
+
+    for (const name of result.rolledBack) {
+      console.log(`${green('✓')} ${name}`)
+    }
+
+    console.log(`\n${green('Rolled back:')} ${result.rolledBack.length} file(s) ${dim(`(batch ${result.batch})`)}\n`)
+  } catch (err) {
+    console.error(`\n${red('Rollback failed:')}\n${err.message}\n`)
+    process.exit(1)
+  }
+}

package/src/commands/migrate-status.js

@@ -0,0 +1,41 @@
+/**
+ * migrate:status command
+ * Shows which migrations have run
+ */
+
+import { createMigrator } from '../db/migrator.js'
+import { green, yellow, cyan, dim, red } from '../cli/colors.js'
+
+export async function run(args, flags) {
+  try {
+    const migrator = await createMigrator()
+    const status = await migrator.status()
+
+    if (status.length === 0) {
+      console.log(`\n${yellow('No migrations found.')}\n`)
+      return
+    }
+
+    console.log(`\n${cyan('Migration status:')}\n`)
+
+    const maxNameLen = Math.max(...status.map(s => s.name.length))
+
+    for (const migration of status) {
+      const name = migration.name.padEnd(maxNameLen)
+      const statusIcon = migration.ran ? green('✓ Ran') : yellow('○ Pending')
+      const batch = migration.batch ? dim(` (batch ${migration.batch})`) : ''
+
+      console.log(`  ${statusIcon}  ${name}${batch}`)
+    }
+
+    const ranCount = status.filter(s => s.ran).length
+    const pendingCount = status.filter(s => !s.ran).length
+
+    console.log()
+    console.log(`  ${green('Ran:')} ${ranCount}  ${yellow('Pending:')} ${pendingCount}`)
+    console.log()
+  } catch (err) {
+    console.error(`\n${red('Error:')}\n${err.message}\n`)
+    process.exit(1)
+  }
+}

package/src/commands/migrate.js

@@ -0,0 +1,30 @@
+/**
+ * migrate command
+ * Runs all pending migrations
+ */
+
+import { createMigrator } from '../db/migrator.js'
+import { green, yellow, cyan, dim, red } from '../cli/colors.js'
+
+export async function run(args, flags) {
+  console.log(`\n${cyan('Running migrations...')}\n`)
+
+  try {
+    const migrator = await createMigrator()
+    const result = await migrator.migrate()
+
+    if (result.ran.length === 0) {
+      console.log(`${yellow('Nothing to migrate.')}\n`)
+      return
+    }
+
+    for (const name of result.ran) {
+      console.log(`${green('✓')} ${name}`)
+    }
+
+    console.log(`\n${green('Migrated:')} ${result.ran.length} file(s) ${dim(`(batch ${result.batch})`)}\n`)
+  } catch (err) {
+    console.error(`\n${red('Migration failed:')}\n${err.message}\n`)
+    process.exit(1)
+  }
+}

package/src/commands/seed.js

@@ -0,0 +1,47 @@
+/**
+ * seed command
+ * Runs database seeders to populate data
+ */
+
+import { createSeeder } from '../db/seeder.js'
+import { green, yellow, cyan, dim, red } from '../cli/colors.js'
+
+export async function run(args, flags) {
+  const seedName = args[0]
+
+  if (seedName) {
+    console.log(`\n${cyan(`Running seed: ${seedName}...`)}\n`)
+  } else {
+    console.log(`\n${cyan('Running all seeds...')}\n`)
+  }
+
+  try {
+    const seeder = await createSeeder()
+
+    // Run specific seed or all seeds
+    const result = seedName
+      ? await seeder.run(seedName)
+      : await seeder.runAll()
+
+    if (result.ran.length === 0) {
+      console.log(`${yellow('No seeds to run.')}\n`)
+
+      // Show hint if no seeds directory
+      const available = seeder.list()
+      if (available.length === 0) {
+        console.log(`${dim('Create seed files in seeds/ directory.')}`)
+        console.log(`${dim('Run: basicben make:seed <name>')}\n`)
+      }
+      return
+    }
+
+    for (const name of result.ran) {
+      console.log(`${green('✓')} ${name}`)
+    }
+
+    console.log(`\n${green('Seeded:')} ${result.ran.length} file(s)\n`)
+  } catch (err) {
+    console.error(`\n${red('Seed failed:')}\n${err.message}\n`)
+    process.exit(1)
+  }
+}

package/src/commands/start.js

@@ -0,0 +1,69 @@
+/**
+ * start command
+ * Runs the production server
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { bold, cyan, green, yellow, dim, red } from '../cli/colors.js'
+
+export async function run(args, flags) {
+  const cwd = process.cwd()
+
+  console.log(`\n${bold('BasicBen')} ${dim('start')}\n`)
+
+  // Check for built files
+  const distServer = resolve(cwd, 'dist/server/index.js')
+  const distClient = resolve(cwd, 'dist/client')
+
+  if (!existsSync(distServer)) {
+    console.error(`${red('Error:')} Production build not found.`)
+    console.error(`\nRun ${cyan('basicben build')} first.\n`)
+    process.exit(1)
+  }
+
+  if (!existsSync(distClient)) {
+    console.error(`${yellow('Warning:')} Client build not found at dist/client`)
+  }
+
+  const port = flags.port || process.env.PORT || 3000
+
+  console.log(`${green('Starting production server...')}\n`)
+  console.log(`${cyan('Server')} ${dim('→')} http://localhost:${port}\n`)
+
+  // Start the production server
+  const nodeArgs = ['dist/server/index.js']
+
+  // Add .env file if it exists
+  if (existsSync(resolve(cwd, '.env'))) {
+    nodeArgs.unshift('--env-file=.env')
+  }
+
+  const proc = spawn('node', nodeArgs, {
+    cwd,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      PORT: port,
+      NODE_ENV: 'production'
+    }
+  })
+
+  proc.on('exit', (code) => {
+    if (code !== 0) {
+      console.error(`\n${red('Server exited with code')} ${code}\n`)
+      process.exit(code)
+    }
+  })
+
+  // Handle graceful shutdown
+  const cleanup = () => {
+    console.log(`\n${dim('Shutting down...')}\n`)
+    proc.kill()
+    process.exit(0)
+  }
+
+  process.on('SIGINT', cleanup)
+  process.on('SIGTERM', cleanup)
+}

package/src/commands/test.js

@@ -0,0 +1,46 @@
+/**
+ * test command
+ * Runs Vitest for user app tests
+ */
+
+import { spawn } from 'node:child_process'
+import { bold, cyan, dim } from '../cli/colors.js'
+
+export async function run(args, flags) {
+  const cwd = process.cwd()
+
+  console.log(`\n${bold('BasicBen')} ${dim('test')}\n`)
+
+  // Build vitest args
+  const vitestArgs = ['vitest', ...args]
+
+  // Add common flags
+  if (flags.watch || flags.w) {
+    // Default is watch mode, no flag needed
+  } else if (!args.includes('--watch')) {
+    vitestArgs.push('--run') // Run once and exit
+  }
+
+  if (flags.coverage) {
+    vitestArgs.push('--coverage')
+  }
+
+  if (flags.ui) {
+    vitestArgs.push('--ui')
+  }
+
+  console.log(`${cyan('Running tests with Vitest...')}\n`)
+
+  const proc = spawn('npx', vitestArgs, {
+    cwd,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      NODE_ENV: 'test'
+    }
+  })
+
+  proc.on('exit', (code) => {
+    process.exit(code || 0)
+  })
+}

package/src/db/Grammar.js

@@ -0,0 +1,125 @@
+/**
+ * SQL Grammar - handles dialect differences and identifier escaping.
+ * Provides protection against SQL injection for identifiers (column/table names).
+ */
+
+export class Grammar {
+  constructor(driver = 'sqlite') {
+    this.driver = driver
+  }
+
+  /**
+   * Validate an identifier (column/table name).
+   * Only allows alphanumeric characters and underscores.
+   * Must start with a letter or underscore.
+   *
+   * @param {string} name - The identifier to validate
+   * @returns {string} The validated identifier
+   * @throws {Error} If the identifier is invalid
+   */
+  validateId(name) {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error('Identifier must be a non-empty string')
+    }
+
+    if (name.length > 128) {
+      throw new Error(`Identifier too long: ${name.slice(0, 20)}...`)
+    }
+
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+      throw new Error(
+        `Invalid identifier "${name}". ` +
+        'Identifiers must contain only letters, numbers, and underscores, ' +
+        'and must start with a letter or underscore.'
+      )
+    }
+
+    return name
+  }
+
+  /**
+   * Escape an identifier for safe use in SQL.
+   * Validates first, then wraps in quotes with proper escaping.
+   *
+   * @param {string} name - The identifier to escape
+   * @returns {string} The escaped identifier
+   */
+  escapeId(name) {
+    // Validate first
+    this.validateId(name)
+
+    // MySQL/PlanetScale uses backticks for identifiers
+    if (this.driver === 'planetscale' || this.driver === 'mysql') {
+      return `\`${name.replace(/`/g, '``')}\``
+    }
+
+    // SQLite, Postgres, Turso, Neon use double quotes for identifiers
+    return `"${name.replace(/"/g, '""')}"`
+  }
+
+  /**
+   * Get the placeholder syntax for the current driver.
+   *
+   * @param {number} index - Zero-based parameter index
+   * @returns {string} The placeholder string
+   */
+  placeholder(index) {
+    // Postgres and Neon use $1, $2, etc.
+    if (this.driver === 'postgres' || this.driver === 'pg' || this.driver === 'neon') {
+      return `$${index + 1}`
+    }
+    // SQLite, Turso, PlanetScale use ?
+    return '?'
+  }
+
+  /**
+   * Validate an operator for WHERE clauses.
+   *
+   * @param {string} operator - The operator to validate
+   * @returns {string} The validated operator
+   * @throws {Error} If the operator is not allowed
+   */
+  validateOperator(operator) {
+    const allowed = ['=', '!=', '<>', '<', '>', '<=', '>=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'IS', 'IS NOT']
+    const upper = operator.toUpperCase()
+
+    if (!allowed.includes(upper)) {
+      throw new Error(`Invalid operator: ${operator}`)
+    }
+
+    return upper
+  }
+
+  /**
+   * Validate sort direction.
+   *
+   * @param {string} direction - ASC or DESC
+   * @returns {string} The validated direction
+   */
+  validateDirection(direction) {
+    const upper = (direction || 'ASC').toUpperCase()
+
+    if (upper !== 'ASC' && upper !== 'DESC') {
+      throw new Error(`Invalid sort direction: ${direction}`)
+    }
+
+    return upper
+  }
+
+  /**
+   * Build a column list for SELECT.
+   *
+   * @param {string[]} columns - Array of column names
+   * @returns {string} Escaped column list
+   */
+  columnList(columns) {
+    if (!columns || columns.length === 0) {
+      return '*'
+    }
+
+    return columns.map(col => {
+      if (col === '*') return '*'
+      return this.escapeId(col)
+    }).join(', ')
+  }
+}