@strav/cli 0.4.31 → 1.0.0-alpha.4

package/src/run_cli.ts

@@ -0,0 +1,121 @@
+/**
+ * `runCli` — entry point for `bin/strav.ts`.
+ *
+ * Flow:
+ *   1. Parse argv to find the command name (no app yet).
+ *   2. Look up the matching `CliCommandClass` by signature first-token.
+ *   3. Read its `static providers` (if any) → filter `defaultProviders`
+ *      with transitive deps auto-included.
+ *   4. Build (or accept) the Application. Register the filtered providers.
+ *   5. Hand off to `@strav/kernel`'s `ConsoleKernel.run(...)`, which boots,
+ *      dispatches, and shuts down. Per-command argv binding happens inside
+ *      `Command.handle()` (the kernel calls `handle`, our base re-binds).
+ *
+ * Return: the dispatch's exit code. Callers in `bin/strav.ts` are expected
+ * to forward it via `process.exit(code)`.
+ *
+ * Args:
+ *   - `argv` — typically `process.argv.slice(2)`.
+ *   - `defaultProviders` — the full provider list from `bootstrap/providers.ts`.
+ *   - `commands` — optional explicit command list. When omitted, every
+ *     `ConsoleProvider` subclass found in `defaultProviders` contributes its
+ *     `commands` array.
+ *   - `app` — pre-built Application (tests). When omitted, one is constructed.
+ */
+
+import {
+  type Application,
+  ConfigError,
+  ConsoleKernel,
+  type ConsoleOutputOptions,
+  parseArgv,
+  type ServiceProvider,
+} from '@strav/kernel'
+import type { CliCommandClass } from './command.ts'
+import { collectCommands } from './console_provider.ts'
+import { selectProviders } from './subset_boot.ts'
+
+export interface RunCliOptions {
+  argv: readonly string[]
+  /** Full default provider list — typically from `bootstrap/providers.ts`. */
+  defaultProviders: readonly ServiceProvider[]
+  /**
+   * Explicit command list. Optional — when omitted, commands are collected
+   * from every `ConsoleProvider` subclass in `defaultProviders`.
+   */
+  commands?: readonly CliCommandClass[]
+  /** Pre-built application (tests). */
+  app?: Application
+  output?: ConsoleOutputOptions
+  /** Install SIGINT/SIGTERM handlers. Default `false` for console. */
+  signalHandlers?: boolean
+}
+
+export async function runCli(options: RunCliOptions): Promise<number> {
+  const commands = options.commands ?? collectCommands(options.defaultProviders)
+  assertUniqueCommands(commands)
+  const byName = indexByName(commands)
+  const { command: commandName } = parseArgv(options.argv)
+
+  // ─── pick the subset of providers to boot ──────────────────────────────────
+  // No command (or `list` / `--help`) → boot nothing; the kernel just prints
+  // the registered list. Apps that wire a custom listing command can override.
+  let providers: ServiceProvider[]
+  if (
+    commandName === undefined ||
+    commandName === 'list' ||
+    commandName === '--help' ||
+    commandName === '-h'
+  ) {
+    providers = []
+  } else {
+    const Class = byName.get(commandName)
+    const requested = (Class as { providers?: readonly string[] } | undefined)?.providers
+    providers = selectProviders(options.defaultProviders, requested, commandName)
+  }
+
+  // ─── delegate to kernel's ConsoleKernel.run ────────────────────────────────
+  const runArgs: {
+    argv: readonly string[]
+    providers: ServiceProvider[]
+    commands: readonly CliCommandClass[]
+    signalHandlers: boolean
+    app?: Application
+    output?: ConsoleOutputOptions
+  } = {
+    argv: options.argv,
+    providers,
+    commands,
+    signalHandlers: options.signalHandlers ?? false,
+  }
+  if (options.app !== undefined) runArgs.app = options.app
+  if (options.output !== undefined) runArgs.output = options.output
+  return ConsoleKernel.run(runArgs)
+}
+
+function assertUniqueCommands(commands: readonly CliCommandClass[]): void {
+  const seen = new Map<string, CliCommandClass>()
+  for (const Class of commands) {
+    const name = firstToken(Class.signature)
+    const existing = seen.get(name)
+    if (existing) {
+      throw new ConfigError(
+        `runCli: command "${name}" declared twice (${existing.name} and ${Class.name})`,
+      )
+    }
+    seen.set(name, Class)
+  }
+}
+
+function indexByName(commands: readonly CliCommandClass[]): Map<string, CliCommandClass> {
+  const out = new Map<string, CliCommandClass>()
+  for (const Class of commands) out.set(firstToken(Class.signature), Class)
+  return out
+}
+
+/** Pull the command name (first whitespace-delimited token) out of a signature. */
+function firstToken(signature: string): string {
+  const trimmed = signature.trimStart()
+  const space = trimmed.search(/\s/)
+  return space === -1 ? trimmed : trimmed.slice(0, space)
+}

package/src/scaffold_console_provider.ts

@@ -0,0 +1,45 @@
+/**
+ * `ScaffoldConsoleProvider` — all `make:*` commands.
+ *
+ * Apps add it to `bootstrap/providers.ts`. Because all make:* commands
+ * set `static providers = []` (boot nothing), the startup cost is zero
+ * when a scaffolding command runs.
+ */
+
+import { ConsoleProvider } from './console_provider.ts'
+import { MakeCommandFile } from './make/make_command_file.ts'
+import { MakeController } from './make/make_controller.ts'
+import { MakeFactory } from './make/make_factory.ts'
+import { MakeJob } from './make/make_job.ts'
+import { MakeMail } from './make/make_mail.ts'
+import { MakeMiddleware } from './make/make_middleware.ts'
+import { MakeMigration } from './make/make_migration.ts'
+import { MakeModel } from './make/make_model.ts'
+import { MakeNotification } from './make/make_notification.ts'
+import { MakePolicy } from './make/make_policy.ts'
+import { MakeProvider } from './make/make_provider.ts'
+import { MakeRepository } from './make/make_repository.ts'
+import { MakeRequest } from './make/make_request.ts'
+import { MakeSeeder } from './make/make_seeder.ts'
+import { MakeTest } from './make/make_test.ts'
+
+export class ScaffoldConsoleProvider extends ConsoleProvider {
+  override readonly name = 'console.scaffold'
+  override readonly commands = [
+    MakeController,
+    MakeMiddleware,
+    MakeRequest,
+    MakeModel,
+    MakeRepository,
+    MakeMigration,
+    MakeSeeder,
+    MakeFactory,
+    MakeJob,
+    MakeMail,
+    MakeNotification,
+    MakePolicy,
+    MakeProvider,
+    MakeCommandFile,
+    MakeTest,
+  ] as const
+}

package/src/signature.ts

@@ -0,0 +1,171 @@
+/**
+ * Signature DSL — parses `'cmd {arg} {arg?} {--flag=default} {--bool}'` into
+ * a structured `Signature` the `Command` base + `CliConsoleKernel` use to
+ * dispatch argv onto `execute({ args, flags })`.
+ *
+ * Grammar (each piece separated by whitespace):
+ *   - `name`               → command name (first token, no curlies).
+ *   - `{slug}`             → required positional named `slug`.
+ *   - `{target?}`          → optional positional named `target` (undefined when missing).
+ *   - `{--output}`         → boolean flag named `output` (default `false`).
+ *   - `{--output=val}`     → string flag named `output` (default `'val'`).
+ *
+ * Constraints (enforced by `parseSignature`):
+ *   - First token IS the command name and never carries `{}`.
+ *   - All required positionals come before optionals.
+ *   - Positional + flag names are unique within a signature.
+ *
+ * Unknown shapes throw `ConfigError` at parse time — typos surface at command
+ * registration, not at the user's first attempt to run.
+ */
+
+import { ConfigError } from '@strav/kernel'
+
+export interface PositionalArg {
+  /** Identifier accessible as `args.<name>` in execute(). */
+  name: string
+  optional: boolean
+}
+
+export type FlagSpec =
+  | {
+      kind: 'boolean'
+      name: string
+      /** Always `false` — bare `--flag` flips it to `true`. */
+      default: false
+    }
+  | {
+      kind: 'string'
+      name: string
+      /** Default returned when the flag is absent. */
+      default: string
+    }
+
+export interface Signature {
+  /** Command name — what users type as the first argv token. */
+  name: string
+  args: PositionalArg[]
+  flags: FlagSpec[]
+}
+
+/**
+ * Parse a signature string into a structured `Signature`. Throws `ConfigError`
+ * with a clear message on any malformed token.
+ */
+export function parseSignature(signature: string): Signature {
+  const tokens = tokenize(signature)
+  if (tokens.length === 0) {
+    throw new ConfigError(`parseSignature: empty signature`)
+  }
+  const first = tokens[0] ?? ''
+  if (first.startsWith('{')) {
+    throw new ConfigError(
+      `parseSignature("${signature}"): first token must be the command name, not "${first}"`,
+    )
+  }
+  const name = first
+
+  const args: PositionalArg[] = []
+  const flags: FlagSpec[] = []
+  const seenArgNames = new Set<string>()
+  const seenFlagNames = new Set<string>()
+  let sawOptional = false
+
+  for (let i = 1; i < tokens.length; i++) {
+    const tok = tokens[i] ?? ''
+    if (!tok.startsWith('{') || !tok.endsWith('}')) {
+      throw new ConfigError(`parseSignature("${signature}"): token "${tok}" must be wrapped in {…}`)
+    }
+    const inner = tok.slice(1, -1)
+    if (inner.startsWith('--')) {
+      const flag = parseFlag(inner.slice(2), signature)
+      if (seenFlagNames.has(flag.name)) {
+        throw new ConfigError(
+          `parseSignature("${signature}"): flag "--${flag.name}" declared twice`,
+        )
+      }
+      seenFlagNames.add(flag.name)
+      flags.push(flag)
+    } else {
+      const arg = parsePositional(inner, signature)
+      if (seenArgNames.has(arg.name)) {
+        throw new ConfigError(
+          `parseSignature("${signature}"): positional "${arg.name}" declared twice`,
+        )
+      }
+      if (sawOptional && !arg.optional) {
+        throw new ConfigError(
+          `parseSignature("${signature}"): required positional "${arg.name}" cannot follow an optional one — argv parsing would be ambiguous`,
+        )
+      }
+      if (arg.optional) sawOptional = true
+      seenArgNames.add(arg.name)
+      args.push(arg)
+    }
+  }
+
+  return { name, args, flags }
+}
+
+function parsePositional(inner: string, signature: string): PositionalArg {
+  if (inner.endsWith('?')) {
+    const name = inner.slice(0, -1)
+    validateIdentifier(name, signature)
+    return { name, optional: true }
+  }
+  validateIdentifier(inner, signature)
+  return { name: inner, optional: false }
+}
+
+function parseFlag(inner: string, signature: string): FlagSpec {
+  const eq = inner.indexOf('=')
+  if (eq === -1) {
+    validateIdentifier(inner, signature)
+    return { kind: 'boolean', name: inner, default: false }
+  }
+  const name = inner.slice(0, eq)
+  const value = inner.slice(eq + 1)
+  validateIdentifier(name, signature)
+  return { kind: 'string', name, default: value }
+}
+
+function validateIdentifier(name: string, signature: string): void {
+  if (name.length === 0) {
+    throw new ConfigError(`parseSignature("${signature}"): empty identifier`)
+  }
+  // Allow letters, digits, dash, underscore. CLI flag/arg names mirror what
+  // users would type — kebab-case is fine.
+  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name)) {
+    throw new ConfigError(
+      `parseSignature("${signature}"): "${name}" is not a valid identifier (letters, digits, dash, underscore; must start with a letter)`,
+    )
+  }
+}
+
+/**
+ * Tokenize on whitespace, but keep braced groups intact even if they contain
+ * spaces (`{--header=Authorization: Bearer}` works). Throws on unterminated
+ * braces.
+ */
+function tokenize(signature: string): string[] {
+  const tokens: string[] = []
+  let i = 0
+  while (i < signature.length) {
+    while (i < signature.length && /\s/.test(signature[i] ?? '')) i++
+    if (i >= signature.length) break
+    if (signature[i] === '{') {
+      const end = signature.indexOf('}', i)
+      if (end === -1) {
+        throw new ConfigError(`parseSignature("${signature}"): unterminated "{"`)
+      }
+      tokens.push(signature.slice(i, end + 1))
+      i = end + 1
+    } else {
+      let j = i
+      while (j < signature.length && !/\s/.test(signature[j] ?? '')) j++
+      tokens.push(signature.slice(i, j))
+      i = j
+    }
+  }
+  return tokens
+}

package/src/subset_boot.ts

@@ -0,0 +1,51 @@
+/**
+ * Subset boot — given the default provider list and a list of provider names
+ * requested by a command's `static providers`, return the filtered list with
+ * transitive `dependencies` auto-included.
+ *
+ * Spec:
+ *   - `undefined` → return the full default list (no filtering).
+ *   - `[]`        → return an empty array.
+ *   - `[names...]` → look each name up in the default list; pull in every
+ *     transitive `dependencies = [...]` entry; topo-order preserved by the
+ *     application's own sort.
+ *   - Unknown name → `ConfigError` with a clear message.
+ */
+
+import { ConfigError, type ServiceProvider } from '@strav/kernel'
+
+export function selectProviders(
+  defaults: readonly ServiceProvider[],
+  requested: readonly string[] | undefined,
+  commandName: string,
+): ServiceProvider[] {
+  if (requested === undefined) return [...defaults]
+  if (requested.length === 0) return []
+
+  const byName = new Map<string, ServiceProvider>()
+  for (const p of defaults) byName.set(p.name, p)
+
+  const selected = new Map<string, ServiceProvider>()
+
+  const visit = (name: string, trail: readonly string[]): void => {
+    if (selected.has(name)) return
+    if (trail.includes(name)) {
+      throw new ConfigError(
+        `ConsoleProvider: circular provider dependency while resolving '${commandName}': ${[...trail, name].join(' → ')}`,
+      )
+    }
+    const provider = byName.get(name)
+    if (!provider) {
+      throw new ConfigError(
+        `Command '${commandName}' declared provider '${name}' which is not in the default providers list`,
+      )
+    }
+    for (const dep of provider.dependencies) {
+      visit(dep, [...trail, name])
+    }
+    selected.set(name, provider)
+  }
+
+  for (const name of requested) visit(name, [])
+  return [...selected.values()]
+}

package/src/util_console_provider.ts

@@ -0,0 +1,18 @@
+/**
+ * `UtilConsoleProvider` — utility commands that don't belong to a specific
+ * package (key generation, config introspection).
+ *
+ * `KeyGenerate` sets `static providers = []` (writes to disk, no app services).
+ * `ConfigShow` / `ConfigList` set `static providers = ['config']` to read
+ * from the booted `ConfigRepository`.
+ */
+
+import { ConfigList } from './config_list.ts'
+import { ConfigShow } from './config_show.ts'
+import { ConsoleProvider } from './console_provider.ts'
+import { KeyGenerate } from './key_generate.ts'
+
+export class UtilConsoleProvider extends ConsoleProvider {
+  override readonly name = 'console.util'
+  override readonly commands = [KeyGenerate, ConfigShow, ConfigList] as const
+}

package/src/cli/bootstrap.ts

@@ -1,82 +0,0 @@
-import Configuration from '@strav/kernel/config/configuration'
-import Database from '@strav/database/database/database'
-import SchemaRegistry from '@strav/database/schema/registry'
-import DatabaseIntrospector from '@strav/database/database/introspector'
-import Application, { app } from '@strav/kernel/core/application'
-import type ServiceProvider from '@strav/kernel/core/service_provider'
-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.
- */
-export async function bootstrap(): Promise<BootstrapResult> {
-  const config = new Configuration('./config')
-  await config.load()
-
-  const db = new Database(config)
-  await db.init()
-
-  const registry = new SchemaRegistry()
-  const dbPaths = await getDatabasePaths()
-  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()
-}
-
-export interface WithProvidersOptions {
-  /**
-   * Install SIGINT/SIGTERM handlers for graceful shutdown. Default: `true`.
-   * Set to `false` when the caller owns signal handling and must control
-   * shutdown ordering — e.g. `queue:work`, which lets the worker drain its
-   * in-flight job before `app.shutdown()` tears down providers.
-   */
-  signalHandlers?: boolean
-}
-
-/**
- * Bootstrap the global Application with the given service providers.
- *
- * Registers all providers on the global `app` singleton from `@strav/kernel`,
- * boots them in dependency order, and returns it. Signal handlers for
- * graceful shutdown are installed automatically unless `options.signalHandlers`
- * is `false`.
- *
- * The global singleton is intentional: handler code (queue handlers, scheduled
- * tasks, route handlers, etc.) commonly imports `app` from `@strav/kernel` to
- * resolve services. A separate Application instance here would leave that
- * singleton's container empty and cause `app.resolve(X)` to throw at runtime —
- * a silent failure mode for queue workers in particular.
- *
- * @example
- * const app = await withProviders([
- *   new ConfigProvider(),
- *   new DatabaseProvider(),
- *   new AuthProvider({ resolver: (id) => User.find(id) }),
- * ])
- */
-export async function withProviders(
-  providers: ServiceProvider[],
-  options?: WithProvidersOptions,
-): Promise<Application> {
-  for (const provider of providers) app.use(provider)
-  await app.start(options)
-  return app
-}

package/src/cli/command_loader.ts

@@ -1,180 +0,0 @@
-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 `@strav/*` 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. @strav/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/@strav/*
-    const nodeModulesDir = join(root, 'node_modules', '@strav')
-    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

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

package/src/cli/strav.ts

@@ -1,13 +0,0 @@
-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()