@strav/cli 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@strav/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CLI framework and code generators for the Strav framework",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "framework",
+    "typescript",
+    "strav",
+    "cli"
+  ],
+  "strav": {
+    "commands": "src/commands"
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./cli": "./src/cli/index.ts",
+    "./cli/*": "./src/cli/*.ts",
+    "./commands": "./src/commands/index.ts",
+    "./commands/*": "./src/commands/*.ts",
+    "./generators": "./src/generators/index.ts",
+    "./generators/*": "./src/generators/*.ts"
+  },
+  "bin": {
+    "strav": "./src/cli/strav.ts"
+  },
+  "peerDependencies": {
+    "@strav/kernel": "0.1.0",
+    "@strav/http": "0.1.0",
+    "@strav/database": "0.1.0",
+    "@strav/queue": "0.1.0",
+    "@strav/signal": "0.1.0"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "prettier": "^3.8.1"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/cli/bootstrap.ts

@@ -0,0 +1,79 @@
+import Configuration from '@stravigor/kernel/config/configuration'
+import Database from '@stravigor/database/database/database'
+import SchemaRegistry from '@stravigor/database/schema/registry'
+import DatabaseIntrospector from '@stravigor/database/database/introspector'
+import Application from '@stravigor/kernel/core/application'
+import type ServiceProvider from '@stravigor/kernel/core/service_provider'
+import { discoverDomains } from '@stravigor/database'
+import { getDatabasePaths } from '../config/loader.ts'
+
+export interface BootstrapResult {
+  config: Configuration
+  db: Database
+  registry: SchemaRegistry
+  introspector: DatabaseIntrospector
+}
+
+/**
+ * Bootstrap the core framework services needed by CLI commands.
+ *
+ * Loads configuration, connects to the database, discovers and validates
+ * schemas, and creates an introspector instance.
+ *
+ * @param scope - Optional domain to discover schemas from (e.g., 'public', 'tenant', 'factory')
+ */
+export async function bootstrap(scope?: string): Promise<BootstrapResult> {
+  const config = new Configuration('./config')
+  await config.load()
+
+  const db = new Database(config)
+
+  const registry = new SchemaRegistry()
+
+  // Get the configured database paths
+  const dbPaths = await getDatabasePaths()
+
+  if (scope && scope !== 'public') {
+    // For non-public domains, we need to load public schemas first since they may reference them
+    await registry.discover(dbPaths.schemas, 'public')
+    await registry.discover(dbPaths.schemas, scope)
+  } else if (scope === 'public') {
+    // For public schemas, only load public
+    await registry.discover(dbPaths.schemas, 'public')
+  } else {
+    // Default: discover all schemas (backward compatibility)
+    await registry.discover(dbPaths.schemas)
+  }
+
+  registry.validate()
+
+  const introspector = new DatabaseIntrospector(db)
+
+  return { config, db, registry, introspector }
+}
+
+/** Cleanly close the database connection. */
+export async function shutdown(db: Database): Promise<void> {
+  await db.close()
+}
+
+/**
+ * Bootstrap an Application with the given service providers.
+ *
+ * Creates a fresh Application, registers all providers, boots them
+ * in dependency order, and returns the running application.
+ * Signal handlers for graceful shutdown are installed automatically.
+ *
+ * @example
+ * const app = await withProviders([
+ *   new ConfigProvider(),
+ *   new DatabaseProvider(),
+ *   new AuthProvider({ resolver: (id) => User.find(id) }),
+ * ])
+ */
+export async function withProviders(providers: ServiceProvider[]): Promise<Application> {
+  const app = new Application()
+  for (const provider of providers) app.use(provider)
+  await app.start()
+  return app
+}

package/src/cli/command_loader.ts

@@ -0,0 +1,180 @@
+import { readdirSync, existsSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import chalk from 'chalk'
+
+/**
+ * Discovers and registers CLI commands from two sources:
+ *
+ * 1. **Package commands** — installed `@stravigor/*` packages that declare
+ *    `"strav": { "commands": "src/commands" }` in their `package.json`.
+ * 2. **User commands** — `.ts` files in a `./commands/` directory at the
+ *    project root.
+ *
+ * Every discovered file must export a `register(program: Command): void`
+ * function.
+ *
+ * @example
+ * // In strav.ts:
+ * await CommandLoader.discover(program)
+ *
+ * @example
+ * // In a package (e.g. @stravigor/search):
+ * // package.json: { "strav": { "commands": "src/commands" } }
+ * // src/commands/search_import.ts:
+ * export function register(program: Command): void {
+ *   program.command('search:import <model>').action(async () => { ... })
+ * }
+ *
+ * @example
+ * // User-defined command:
+ * // commands/deploy.ts:
+ * export function register(program: Command): void {
+ *   program.command('deploy').action(async () => { ... })
+ * }
+ */
+export default class CommandLoader {
+  /**
+   * Discover and register commands from packages and the user's commands directory.
+   *
+   * @param baseDir - Project root directory. Defaults to `process.cwd()`.
+   */
+  static async discover(program: Command, baseDir?: string): Promise<void> {
+    const root = baseDir ?? process.cwd()
+    await this.loadPackageCommands(program, root)
+    await this.loadUserCommands(program, root)
+  }
+
+  // ── Package commands ───────────────────────────────────────────────────
+
+  private static async loadPackageCommands(program: Command, root: string): Promise<void> {
+    const packages = await this.resolvePackages(root)
+
+    for (const { root: pkgRoot, commandsDir } of packages) {
+      try {
+        const dir = join(pkgRoot, commandsDir)
+        if (!dirExists(dir)) continue
+
+        const files = readdirSync(dir).filter(f => f.endsWith('.ts'))
+        for (const file of files) {
+          const filePath = join(dir, file)
+          try {
+            const module = await import(filePath)
+            if (typeof module.register === 'function') {
+              module.register(program)
+            }
+          } catch (err) {
+            console.error(
+              chalk.yellow(
+                `Warning: Failed to load command "${file}": ${err instanceof Error ? err.message : err}`
+              )
+            )
+          }
+        }
+      } catch {
+        // Skip packages whose commands directory can't be read
+      }
+    }
+  }
+
+  // ── User commands ──────────────────────────────────────────────────────
+
+  private static async loadUserCommands(program: Command, root: string): Promise<void> {
+    const userDir = join(root, 'commands')
+    if (!dirExists(userDir)) return
+
+    const files = readdirSync(userDir).filter(f => f.endsWith('.ts'))
+
+    for (const file of files) {
+      const filePath = join(userDir, file)
+      try {
+        const module = await import(filePath)
+        if (typeof module.register === 'function') {
+          module.register(program)
+        }
+      } catch (err) {
+        console.error(
+          chalk.yellow(
+            `Warning: Failed to load command "${file}": ${err instanceof Error ? err.message : err}`
+          )
+        )
+      }
+    }
+  }
+
+  // ── Package resolution ─────────────────────────────────────────────────
+
+  private static async resolvePackages(
+    root: string
+  ): Promise<Array<{ root: string; commandsDir: string }>> {
+    const results: Array<{ root: string; commandsDir: string }> = []
+    const seen = new Set<string>()
+
+    // 1. Check node_modules/@stravigor/*
+    const nodeModulesDir = join(root, 'node_modules', '@stravigor')
+    if (dirExists(nodeModulesDir)) {
+      const dirs = readdirSync(nodeModulesDir)
+      for (const dir of dirs) {
+        const pkgRoot = join(nodeModulesDir, dir)
+        const realRoot = realPath(pkgRoot)
+        if (seen.has(realRoot)) continue
+        seen.add(realRoot)
+        const commandsDir = await readStravCommands(pkgRoot)
+        if (commandsDir) results.push({ root: pkgRoot, commandsDir })
+      }
+    }
+
+    // 2. Check Bun workspace packages
+    try {
+      const rootPkgPath = join(root, 'package.json')
+      if (existsSync(rootPkgPath)) {
+        const rootPkg = await Bun.file(rootPkgPath).json()
+        const workspaces: string[] = rootPkg.workspaces ?? []
+        for (const ws of workspaces) {
+          const wsPath = join(root, ws)
+          const realRoot = realPath(wsPath)
+          if (seen.has(realRoot)) continue
+          seen.add(realRoot)
+          const commandsDir = await readStravCommands(wsPath)
+          if (commandsDir) results.push({ root: wsPath, commandsDir })
+        }
+      }
+    } catch {
+      // No package.json or not in a workspace
+    }
+
+    return results
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+/** Resolve symlinks to avoid double-loading workspace packages. */
+function realPath(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+function dirExists(path: string): boolean {
+  try {
+    readdirSync(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Read the `strav.commands` field from a package's `package.json`. */
+async function readStravCommands(packageRoot: string): Promise<string | null> {
+  try {
+    const pkgPath = join(packageRoot, 'package.json')
+    if (!existsSync(pkgPath)) return null
+    const pkg = await Bun.file(pkgPath).json()
+    return pkg?.strav?.commands ?? null
+  } catch {
+    return null
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,3 @@
+export { bootstrap, shutdown, withProviders } from './bootstrap'
+export type { BootstrapResult } from './bootstrap'
+export { default as CommandLoader } from './command_loader'

package/src/cli/strav.ts

@@ -0,0 +1,13 @@
+import 'reflect-metadata'
+import { Command } from 'commander'
+import { join } from 'node:path'
+import CommandLoader from './command_loader.ts'
+
+const pkg = await Bun.file(join(import.meta.dir, '../../package.json')).json()
+const program = new Command()
+
+program.name('strav').description('Strav CLI').version(pkg.version)
+
+await CommandLoader.discover(program)
+
+program.parse()

package/src/commands/db_seed.ts

@@ -0,0 +1,77 @@
+import { join } from 'node:path'
+import { existsSync } from 'node:fs'
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { bootstrap, shutdown } from '../cli/bootstrap.ts'
+import { freshDatabase, requireLocalEnv } from './migration_fresh.ts'
+import { toSnakeCase } from '@stravigor/kernel/helpers/strings'
+import BaseModel from '@stravigor/database/orm/base_model'
+import { Seeder } from '@stravigor/database/database/seeder'
+
+const SEEDERS_PATH = 'database/seeders'
+
+export function register(program: Command): void {
+  program
+    .command('seed')
+    .alias('db:seed')
+    .description('Seed the database with records')
+    .option('-c, --class <name>', 'Run a specific seeder class')
+    .option('--fresh', 'Drop all tables and re-migrate before seeding')
+    .action(async ({ class: className, fresh }: { class?: string; fresh?: boolean }) => {
+      let db
+      try {
+        const { db: database, registry, introspector } = await bootstrap()
+        db = database
+
+        // Wire BaseModel so factories / seeders can use the ORM
+        new BaseModel(db)
+
+        // --fresh: reset the database first
+        if (fresh) {
+          requireLocalEnv('seed --fresh')
+
+          const applied = await freshDatabase(db, registry, introspector)
+          console.log(chalk.green(`\nFresh migration complete. Applied ${applied} migration(s).`))
+        }
+
+        // Resolve the seeder file
+        const fileName = className
+          ? toSnakeCase(className.replace(/Seeder$/i, '') || 'database') + '_seeder'
+          : 'database_seeder'
+
+        const seederPath = join(process.cwd(), SEEDERS_PATH, `${fileName}.ts`)
+
+        if (!existsSync(seederPath)) {
+          console.error(chalk.red(`Seeder not found: `) + chalk.dim(seederPath))
+          console.error(
+            chalk.dim(
+              `  Run ${chalk.cyan(`strav generate:seeder ${className ?? 'DatabaseSeeder'}`)} to create it.`
+            )
+          )
+          process.exit(1)
+        }
+
+        console.log(chalk.cyan(`\nSeeding database...`))
+
+        const mod = await import(seederPath)
+        const SeederClass = mod.default
+
+        if (!SeederClass || !(SeederClass.prototype instanceof Seeder)) {
+          console.error(
+            chalk.red(`Error: `) + `Default export of ${fileName}.ts must extend Seeder.`
+          )
+          process.exit(1)
+        }
+
+        const seeder = new SeederClass(db) as Seeder
+        await seeder.run()
+
+        console.log(chalk.green('Database seeding complete.'))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+}

package/src/commands/generate_api.ts

@@ -0,0 +1,74 @@
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import SchemaRegistry from '@stravigor/database/schema/registry'
+import ApiGenerator from '../generators/api_generator.ts'
+import RouteGenerator from '../generators/route_generator.ts'
+import TestGenerator from '../generators/test_generator.ts'
+import DocGenerator from '../generators/doc_generator.ts'
+import type { ApiRoutingConfig } from '../generators/route_generator.ts'
+import type { GeneratorConfig } from '../generators/config.ts'
+import { loadGeneratorConfig, getDatabasePaths } from '../config/loader.ts'
+
+export function register(program: Command): void {
+  program
+    .command('generate:api')
+    .alias('g:api')
+    .description(
+      'Generate services, controllers, policies, validators, events, and routes from schemas'
+    )
+    .action(async () => {
+      try {
+        console.log(chalk.cyan('Generating API layer from schemas...'))
+
+        // Get configured database paths
+        const dbPaths = await getDatabasePaths()
+
+        const registry = new SchemaRegistry()
+        await registry.discover(dbPaths.schemas)
+        registry.validate()
+
+        const schemas = registry.resolve()
+        const representation = registry.buildRepresentation()
+
+        // Load generator config (if available)
+        const config = await loadGeneratorConfig()
+
+        const apiGen = new ApiGenerator(schemas, representation, config)
+        const apiFiles = await apiGen.writeAll()
+
+        // Load API routing config from config/http.ts (if available)
+        let apiConfig: Partial<ApiRoutingConfig> | undefined
+        try {
+          const httpConfig = (await import(join(process.cwd(), 'config/http.ts'))).default
+          apiConfig = httpConfig.api
+        } catch {
+          // No config/http.ts or no api section — use defaults
+        }
+
+        const routeGen = new RouteGenerator(schemas, config, apiConfig)
+        const routeFiles = await routeGen.writeAll()
+
+        const testGen = new TestGenerator(schemas, representation, config, apiConfig)
+        const testFiles = await testGen.writeAll()
+
+        const docGen = new DocGenerator(schemas, representation, config, apiConfig)
+        const docFiles = await docGen.writeAll()
+
+        const files = [...apiFiles, ...routeFiles, ...testFiles, ...docFiles]
+
+        if (files.length === 0) {
+          console.log(chalk.yellow('No API files to generate.'))
+          return
+        }
+
+        console.log(chalk.green(`\nGenerated ${files.length} file(s):`))
+        for (const file of files) {
+          console.log(chalk.dim(`  ${file.path}`))
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      }
+    })
+}

package/src/commands/generate_key.ts

@@ -0,0 +1,47 @@
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import chalk from 'chalk'
+
+export function register(program: Command): void {
+  program
+    .command('generate:key')
+    .alias('g:key')
+    .description('Generate an APP_KEY and write it to the .env file')
+    .option('-f, --force', 'Overwrite existing APP_KEY if present')
+    .action(async ({ force }: { force?: boolean }) => {
+      try {
+        const key = crypto.randomUUID()
+        const envPath = join(process.cwd(), '.env')
+        const file = Bun.file(envPath)
+
+        if (await file.exists()) {
+          const contents = await file.text()
+          const hasKey = /^APP_KEY\s*=/m.test(contents)
+
+          if (hasKey && !force) {
+            const current = contents.match(/^APP_KEY\s*=\s*(.*)$/m)?.[1] ?? ''
+            if (current) {
+              console.log(chalk.yellow('APP_KEY already exists in .env. Use --force to overwrite.'))
+              return
+            }
+          }
+
+          if (hasKey) {
+            const updated = contents.replace(/^APP_KEY\s*=.*$/m, `APP_KEY=${key}`)
+            await Bun.write(envPath, updated)
+          } else {
+            const separator = contents.endsWith('\n') ? '' : '\n'
+            await Bun.write(envPath, contents + separator + `APP_KEY=${key}\n`)
+          }
+        } else {
+          await Bun.write(envPath, `APP_KEY=${key}\n`)
+        }
+
+        console.log(chalk.green('APP_KEY generated successfully.'))
+        console.log(chalk.dim(`  ${key}`))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      }
+    })
+}

package/src/commands/generate_models.ts

@@ -0,0 +1,117 @@
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import SchemaRegistry from '@stravigor/database/schema/registry'
+import ModelGenerator from '../generators/model_generator.ts'
+import type { GeneratorConfig } from '../generators/config.ts'
+import { discoverDomains } from '@stravigor/database'
+import { loadGeneratorConfig, getDatabasePaths } from '../config/loader.ts'
+
+export function register(program: Command): void {
+  program
+    .command('generate:models')
+    .alias('g:models')
+    .description('Generate model classes and enums from schema definitions')
+    .option('--scope <scope>', 'Generate models for specific domain or "all" for all domains', 'all')
+    .action(async (options) => {
+      try {
+        const scope = options.scope as string
+
+        // Get configured database paths
+        const dbPaths = await getDatabasePaths()
+
+        // Validate scope against available domains or 'all'
+        const availableDomains = discoverDomains(dbPaths.schemas)
+        if (scope !== 'all' && !availableDomains.includes(scope)) {
+          console.error(chalk.red(`Invalid domain: ${scope}. Available domains: ${availableDomains.join(', ')}, all`))
+          process.exit(1)
+        }
+
+        console.log(chalk.cyan(`Generating models from ${scope === 'all' ? 'all' : scope} schemas...`))
+
+        // Load generator config (if available)
+        const config = await loadGeneratorConfig()
+
+        const allFiles: any[] = []
+        const scopesToProcess = scope === 'all' ? availableDomains : [scope]
+
+        // When generating models for specific domains, we need all schemas loaded
+        // to handle cross-domain references properly
+        const fullRegistry = new SchemaRegistry()
+
+        // Always load public schemas first (base schemas)
+        await fullRegistry.discover(dbPaths.schemas, 'public')
+
+        // Load schemas from all other domains if needed for validation or if generating models for those domains
+        for (const domain of availableDomains) {
+          if (domain !== 'public' && (scope === 'all' || scope === domain)) {
+            await fullRegistry.discover(dbPaths.schemas, domain)
+          }
+        }
+
+        // Validate all loaded schemas
+        fullRegistry.validate()
+
+        // Build representation from all loaded schemas
+        const fullRepresentation = fullRegistry.buildRepresentation()
+
+        // Build a map of schema name -> domain for cross-domain reference resolution
+        const allSchemasMap = new Map<string, string>()
+
+        // Load public schemas to identify which ones are public
+        const publicRegistry = new SchemaRegistry()
+        await publicRegistry.discover(dbPaths.schemas, 'public')
+        const publicSchemaNames = new Set(publicRegistry.all().map(s => s.name))
+
+        // Map schemas to their respective domains by checking which domain directory they came from
+        for (const schema of fullRegistry.all()) {
+          if (publicSchemaNames.has(schema.name)) {
+            allSchemasMap.set(schema.name, 'public')
+          } else {
+            // For non-public schemas, find which domain they belong to
+            // by checking which domains were loaded
+            for (const domain of availableDomains) {
+              if (domain !== 'public') {
+                const domainRegistry = new SchemaRegistry()
+                await domainRegistry.discover(dbPaths.schemas, domain)
+                const domainSchemaNames = new Set(domainRegistry.all().map(s => s.name))
+                if (domainSchemaNames.has(schema.name)) {
+                  allSchemasMap.set(schema.name, domain)
+                  break
+                }
+              }
+            }
+          }
+        }
+
+        for (const currentScope of scopesToProcess) {
+          // Get just the schemas for the current scope
+          const scopeRegistry = new SchemaRegistry()
+          await scopeRegistry.discover(dbPaths.schemas, currentScope)
+
+          if (scopeRegistry.all().length === 0) {
+            console.log(chalk.yellow(`No schemas found for domain: ${currentScope}`))
+            continue
+          }
+
+          const scopeSchemas = scopeRegistry.all()
+          const generator = new ModelGenerator(scopeSchemas, fullRepresentation, config, currentScope, allSchemasMap)
+          const files = await generator.writeAll()
+          allFiles.push(...files)
+        }
+
+        if (allFiles.length === 0) {
+          console.log(chalk.yellow('No models to generate.'))
+          return
+        }
+
+        console.log(chalk.green(`\nGenerated ${allFiles.length} file(s):`))
+        for (const file of allFiles) {
+          console.log(chalk.dim(`  ${file.path}`))
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      }
+    })
+}