@avelonjs/cli 0.1.0

package/src/generate.ts

@@ -0,0 +1,306 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import { snake, studly, type ReeveIO, writeln } from './io'
+
+export interface GenerateOptions {
+  migration?: boolean
+  factory?: boolean
+  controller?: boolean
+  policy?: boolean
+  ward?: boolean
+  resource?: boolean
+  model?: string
+  event?: string
+  queued?: boolean
+}
+
+const builtin: Record<string, string> = {
+  'model.ts': `import { Model } from '@avelonjs/orm'
+
+/** __NAME__ resource model. */
+export class __NAME__ extends Model {
+  static override table = '__TABLE__'
+  static override fillable = ['id']
+
+  declare id: string
+}
+`,
+  'controller.ts': `import { view, type HttpRequest } from '@avelonjs/core'
+
+/** __NAME__ HTTP controller. */
+export class __NAME__ {
+  async index(_request: HttpRequest) {
+    return view('__VIEW__.index', {})
+  }
+}
+`,
+  'resource-controller.ts': `import { redirect, view, type HttpRequest } from '@avelonjs/core'
+
+/** Resource controller for __RESOURCE__. */
+export class __NAME__ {
+  async index() {
+    return view('__VIEW__.index', {})
+  }
+
+  async create() {
+    return view('__VIEW__.create', {})
+  }
+
+  async store(_request: HttpRequest) {
+    return redirect('/__TABLE__')
+  }
+
+  async show(_request: HttpRequest, record: { id: string }) {
+    return view('__VIEW__.show', { id: record.id })
+  }
+
+  async edit(_request: HttpRequest, record: { id: string }) {
+    return view('__VIEW__.edit', { id: record.id })
+  }
+
+  async update(_request: HttpRequest, record: { id: string }) {
+    return redirect(\`/__TABLE__/\${record.id}\`)
+  }
+
+  async destroy(_request: HttpRequest, _record: { id: string }) {
+    return redirect('/__TABLE__')
+  }
+}
+`,
+  'request.ts': `import { defineRequest } from '@avelonjs/core'
+
+/** Input contract for __NAME__. */
+export const __NAME__ = defineRequest({
+  schema: {
+    parse(input: unknown) {
+      return input as Record<string, unknown>
+    },
+  },
+})
+`,
+  'policy.ts': `import { definePolicy } from '@avelonjs/core'
+
+/** Authorization policy for __MODEL__. */
+export const __NAME__ = definePolicy({
+  viewAny: () => true,
+  view: () => true,
+  create: () => true,
+  update: () => false,
+  delete: () => false,
+})
+`,
+  'ward.ts': `import { defineWard } from '@avelonjs/core'
+
+/** Row access rules for __MODEL__. */
+export const __NAME__ = defineWard({
+  read: true,
+  insert: true,
+  update: true,
+  delete: true,
+})
+`,
+  'event.ts': `import { Event } from '@avelonjs/core'
+
+/** Domain event __NAME__. */
+export class __NAME__ extends Event {
+  constructor(readonly id: string) {
+    super()
+  }
+}
+`,
+  'listener.ts': `import { defineListener } from '@avelonjs/core'
+
+/** Listener for __EVENT__. */
+export const __NAME__ = defineListener({
+  delivery: '__DELIVERY__',
+  handle() {},
+})
+`,
+  'errand.ts': `import { defineErrand } from '@avelonjs/core'
+
+/** Background errand __NAME__. */
+export const __NAME__ = defineErrand({
+  name: '__SLUG__',
+  delivery: 'queued',
+  queue: 'default',
+  async handle() {},
+})
+`,
+  'action.ts': `/** Single-purpose action __NAME__. */
+export async function __NAME__() {}
+`,
+  'middleware.ts': `import type { HttpRequest } from '@avelonjs/core'
+
+/** HTTP middleware __NAME__. */
+export async function __NAME__(_request: HttpRequest): Promise<void> {}
+`,
+  'command.ts': `/** Console command __NAME__. */
+export async function __NAME__(): Promise<void> {
+  console.log('__SLUG__')
+}
+`,
+  'view.ts': `/** Opaque view reference for __NAME__. */
+export const __NAME__ = '__SLUG__'
+`,
+  'migration.ts': `/** Driver-owned migration __ID__. */
+export const __NAME__ = {
+  id: '__ID__',
+  async up() {},
+  async down() {},
+}
+`,
+  'factory.ts': `import { defineFactory } from '@avelonjs/assay'
+import { __MODEL__ } from '@/app/Models/__MODEL__'
+
+export default defineFactory(__MODEL__, (sequence) => ({
+  id: \`__TABLE__-\${sequence}\`,
+}))
+`,
+  'package-readme.md': `# @avelonjs/__SLUG__
+
+__INTRO__
+
+## Installation
+
+\`\`\`sh
+bun add @avelonjs/__SLUG__
+\`\`\`
+
+## Basic Usage
+
+\`\`\`ts
+export function ping(): string {
+  return 'pong'
+}
+\`\`\`
+
+## Features
+
+Document each capability here, simple to advanced.
+
+## Method Reference
+
+| Method / export | Signature | Description |
+|---|---|---|
+| \`ping\` | \`() => string\` | Returns pong. |
+
+## Testing
+
+\`\`\`sh
+bun test
+bun run typecheck
+\`\`\`
+`,
+}
+
+function tokens(name: string, extra: Record<string, string> = {}): Record<string, string> {
+  const pascal = studly(name)
+  const table = snake(pascal)
+    .replace(/_controller$/, '')
+    .replace(/_request$/, '')
+    .replace(/_policy$/, '')
+    .replace(/_ward$/, '')
+  return {
+    __NAME__: pascal,
+    __TABLE__: table.endsWith('s') ? table : `${table}s`,
+    __VIEW__: table,
+    __SLUG__: snake(pascal).replace(/_/g, '-'),
+    __RESOURCE__: table,
+    __MODEL__: extra.__MODEL__ ?? pascal.replace(/Policy$|Ward$|Controller$|Request$/, ''),
+    __EVENT__: extra.__EVENT__ ?? 'Event',
+    __DELIVERY__: extra.__DELIVERY__ ?? 'sync',
+    __ID__: extra.__ID__ ?? `20260827_${snake(pascal)}`,
+    __INTRO__: extra.__INTRO__ ?? `${pascal} is an Avelon package.`,
+    ...extra,
+  }
+}
+
+function apply(template: string, vars: Record<string, string>): string {
+  let output = template
+  for (const [key, value] of Object.entries(vars)) output = output.replaceAll(key, value)
+  return output
+}
+
+async function loadTemplate(io: ReeveIO, name: string): Promise<string> {
+  const override = join(io.cwd, 'stubs', name)
+  try {
+    return await readFile(override, 'utf8')
+  } catch {
+    const built = builtin[name]
+    if (built === undefined) throw new Error(`Unknown stub ${name}`)
+    return built
+  }
+}
+
+/** Writes `relative` from a stub, creating parent directories. */
+export async function writeFromStub(
+  io: ReeveIO,
+  stub: string,
+  relative: string,
+  name: string,
+  extra: Record<string, string> = {},
+): Promise<string> {
+  const template = await loadTemplate(io, stub)
+  const file = join(io.cwd, relative)
+  await mkdir(dirname(file), { recursive: true })
+  await writeFile(file, apply(template, tokens(name, extra)))
+  writeln(io, relative)
+  return file
+}
+
+/** Copies built-in stubs into `stubs/` so a team can change generated shape. */
+export async function publishStubs(io: ReeveIO): Promise<readonly string[]> {
+  const written: string[] = []
+  for (const [name, contents] of Object.entries(builtin)) {
+    const file = join(io.cwd, 'stubs', name)
+    await mkdir(dirname(file), { recursive: true })
+    await writeFile(file, contents)
+    written.push(`stubs/${name}`)
+  }
+  writeln(io, `Published ${written.length} stubs.`)
+  return written
+}
+
+/** Generates a model and optional related files from `-mfcpw`. */
+export async function makeModel(
+  io: ReeveIO,
+  name: string,
+  options: GenerateOptions,
+): Promise<void> {
+  const pascal = studly(name)
+  await writeFromStub(io, 'model.ts', `app/Models/${pascal}.ts`, pascal)
+  if (options.migration) await makeMigration(io, `create_${snake(pascal)}s_table`)
+  if (options.factory) {
+    await writeFromStub(io, 'factory.ts', `database/factories/${pascal}Factory.ts`, pascal, {
+      __MODEL__: pascal,
+    })
+  }
+  if (options.controller) {
+    await writeFromStub(
+      io,
+      options.resource ? 'resource-controller.ts' : 'controller.ts',
+      `app/Http/Controllers/${pascal}Controller.ts`,
+      `${pascal}Controller`,
+    )
+  }
+  if (options.policy) {
+    await writeFromStub(io, 'policy.ts', `app/Policies/${pascal}Policy.ts`, `${pascal}Policy`, {
+      __MODEL__: pascal,
+    })
+  }
+  if (options.ward) {
+    await writeFromStub(io, 'ward.ts', `app/Wards/${pascal}Ward.ts`, `${pascal}Ward`, {
+      __MODEL__: pascal,
+    })
+  }
+}
+
+/** Generates a timestamped migration module. */
+export async function makeMigration(io: ReeveIO, name: string): Promise<void> {
+  const slug = snake(name)
+  const id = `${new Date().toISOString().slice(0, 10).replaceAll('-', '')}_${slug}`
+  await writeFromStub(io, 'migration.ts', `database/migrations/${id}.ts`, studly(name), {
+    __ID__: id,
+  })
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+import { runCommand } from './commands'
+import { processIO, shouldUseTui, writeln, type ReeveIO } from './io'
+import { COMMANDS } from './menu'
+
+export { COMMANDS, MENU } from './menu'
+export { shouldUseTui, processIO, type ReeveIO } from './io'
+export { runCommand } from './commands'
+export {
+  checkPackageDocs,
+  runDocsCheck,
+  type DocsCheckResult,
+  type DocsFinding,
+} from './docs-check'
+export { makeDriver, DRIVER_CONTRACTS, type DriverContractSpec } from './driver-scaffold'
+
+/**
+ * Runs `reeve`. Bare invocation opens the TUI when stdout is a TTY. Any subcommand with arguments
+ * skips the TUI entirely. `--no-tui` and a non-TTY stdout force plain mode.
+ */
+export async function runReeve(
+  argv: readonly string[],
+  io: ReeveIO = processIO(),
+): Promise<number> {
+  try {
+    if (shouldUseTui(argv, io)) {
+      const { renderTui } = await import('./tui')
+      await renderTui(io)
+      return 0
+    }
+    const args = argv.filter((arg) => arg !== '--no-tui')
+    const command = args[0]
+    if (command === undefined) {
+      writeln(io, 'Usage: reeve <command>. Bare reeve opens the TUI on a TTY.')
+      writeln(io, `Commands: ${COMMANDS.join(', ')}`)
+      return 1
+    }
+    return await runCommand(command, args.slice(1), io)
+  } catch (error) {
+    writeln(io, error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/io.ts

@@ -0,0 +1,65 @@
+import { stdout as defaultStdout } from 'node:process'
+
+/** IO surface so tests can capture `reeve` without a TTY. */
+export interface ReeveIO {
+  cwd: string
+  stdout: { write(chunk: string): boolean }
+  isTTY: boolean
+  env: Record<string, string | undefined>
+  confirm?: string
+}
+
+/** Builds the default process IO. */
+export function processIO(): ReeveIO {
+  return {
+    cwd: process.cwd(),
+    stdout: defaultStdout,
+    isTTY: Boolean(defaultStdout.isTTY),
+    env: process.env,
+  }
+}
+
+/** Writes a line to the IO stdout. */
+export function writeln(io: ReeveIO, line = ''): void {
+  io.stdout.write(`${line}\n`)
+}
+
+/** Application name, driver, adapter, and environment shown in the TUI header. */
+export function headerBits(io: ReeveIO): {
+  app: string
+  database: string
+  adapter: string
+  environment: string
+} {
+  return {
+    app: io.env.AVELON_APP ?? 'app',
+    database: io.env.AVELON_DATABASE ?? 'unconfigured',
+    adapter: io.env.AVELON_ADAPTER ?? 'next',
+    environment: io.env.AVELON_ENV ?? io.env.NODE_ENV ?? 'local',
+  }
+}
+
+/** True when bare `reeve` should open the TUI. */
+export function shouldUseTui(argv: readonly string[], io: ReeveIO): boolean {
+  if (argv.includes('--no-tui')) return false
+  if (!io.isTTY) return false
+  const rest = argv.filter((arg) => arg !== '--no-tui')
+  return rest.length === 0
+}
+
+/** PascalCase identifier from a user-supplied name. */
+export function studly(name: string): string {
+  return name
+    .split(/[-_\s/]+/)
+    .filter(Boolean)
+    .map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+/** snake_case identifier. */
+export function snake(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .replace(/[-\s/]+/g, '_')
+    .toLowerCase()
+}

package/src/menu.ts

@@ -0,0 +1,53 @@
+/** One TUI row. Every path has a scriptable equivalent. */
+export interface MenuItem {
+  group: string
+  label: string
+  command: string
+}
+
+/** Groups and commands shown in the TUI and used as the CLI catalog. */
+export const MENU: readonly MenuItem[] = [
+  { group: 'Make', label: 'model', command: 'make:model' },
+  { group: 'Make', label: 'controller', command: 'make:controller' },
+  { group: 'Make', label: 'request', command: 'make:request' },
+  { group: 'Make', label: 'policy', command: 'make:policy' },
+  { group: 'Make', label: 'ward', command: 'make:ward' },
+  { group: 'Make', label: 'event', command: 'make:event' },
+  { group: 'Make', label: 'listener', command: 'make:listener' },
+  { group: 'Make', label: 'errand', command: 'make:errand' },
+  { group: 'Make', label: 'action', command: 'make:action' },
+  { group: 'Make', label: 'command', command: 'make:command' },
+  { group: 'Make', label: 'middleware', command: 'make:middleware' },
+  { group: 'Make', label: 'view', command: 'make:view' },
+  { group: 'Make', label: 'driver', command: 'make:driver' },
+  { group: 'Make', label: 'package', command: 'make:package' },
+  { group: 'Make', label: 'auth', command: 'make:auth' },
+  { group: 'Make', label: 'migration', command: 'make:migration' },
+  { group: 'Database', label: 'migrate', command: 'migrate' },
+  { group: 'Database', label: 'rollback', command: 'migrate:rollback' },
+  { group: 'Database', label: 'fresh', command: 'migrate:fresh' },
+  { group: 'Database', label: 'seed', command: 'db:seed' },
+  { group: 'Database', label: 'schema:pull', command: 'schema:pull' },
+  { group: 'Wards', label: 'list', command: 'ward:list' },
+  { group: 'Wards', label: 'sync', command: 'ward:sync' },
+  { group: 'Wards', label: 'check', command: 'ward:check' },
+  { group: 'Wards', label: 'explain', command: 'ward:explain' },
+  { group: 'Routes', label: 'list', command: 'route:list' },
+  { group: 'Routes', label: 'sync', command: 'route:sync' },
+  { group: 'Errands', label: 'work', command: 'errand:work' },
+  { group: 'Errands', label: 'failed', command: 'errand:failed' },
+  { group: 'Errands', label: 'retry', command: 'errand:retry' },
+  { group: 'Errands', label: 'flush', command: 'errand:flush' },
+  { group: 'Inspect', label: 'event:list', command: 'event:list' },
+  { group: 'Inspect', label: 'config:show', command: 'config:show' },
+  { group: 'Inspect', label: 'capabilities', command: 'capabilities' },
+  { group: 'Inspect', label: 'about', command: 'about' },
+  { group: 'Doctor', label: 'bailiff', command: 'bailiff' },
+  { group: 'Doctor', label: 'docs:check', command: 'docs:check' },
+  { group: 'Doctor', label: 'doctor', command: 'doctor' },
+  { group: 'Inspect', label: 'tinker', command: 'tinker' },
+  { group: 'Make', label: 'stub:publish', command: 'stub:publish' },
+]
+
+/** Unique command names the CLI accepts. */
+export const COMMANDS = [...new Set(MENU.map((item) => item.command))]

package/src/tui.tsx

@@ -0,0 +1,77 @@
+import { Box, Text, render, useApp, useInput } from 'ink'
+import { useMemo, useState, type JSX } from 'react'
+
+import { runCommand } from './commands'
+import { headerBits, writeln, type ReeveIO } from './io'
+import { MENU } from './menu'
+
+function ReeveTui(props: { io: ReeveIO }): JSX.Element {
+  const app = useApp()
+  const [cursor, setCursor] = useState(0)
+  const [query, setQuery] = useState('')
+  const [searching, setSearching] = useState(false)
+  const items = useMemo(() => {
+    const needle = query.trim().toLowerCase()
+    if (needle.length === 0) return MENU
+    return MENU.filter(
+      (item) =>
+        item.command.includes(needle) ||
+        item.label.includes(needle) ||
+        item.group.toLowerCase().includes(needle),
+    )
+  }, [query])
+  const current = items[cursor]
+
+  useInput(async (input, key) => {
+    if (searching) {
+      if (key.return || key.escape) {
+        setSearching(false)
+        return
+      }
+      if (key.backspace || key.delete) {
+        setQuery((value) => value.slice(0, -1))
+        return
+      }
+      if (input.length > 0) setQuery((value) => `${value}${input}`)
+      return
+    }
+    if (input === 'q') {
+      app.exit()
+      return
+    }
+    if (input === '/') {
+      setSearching(true)
+      return
+    }
+    if (key.upArrow) setCursor((value) => Math.max(0, value - 1))
+    if (key.downArrow) setCursor((value) => Math.min(items.length - 1, value + 1))
+    if (key.return && current !== undefined) {
+      writeln(props.io, `reeve ${current.command}`)
+      await runCommand(current.command, [], props.io)
+      app.exit()
+    }
+  })
+
+  const bits = headerBits(props.io)
+  return (
+    <Box flexDirection="column" borderStyle="single" paddingX={1}>
+      <Text>
+        avelon {bits.app} · {bits.database} · {bits.adapter} · {bits.environment}
+      </Text>
+      <Text dimColor>
+        {searching ? `search: ${query}` : '↑↓ navigate · ⏎ select · / search · q quit'}
+      </Text>
+      {items.slice(0, 16).map((item, index) => (
+        <Text key={item.command} inverse={index === cursor}>
+          {item.group.padEnd(10)} {item.label.padEnd(14)} {item.command}
+        </Text>
+      ))}
+    </Box>
+  )
+}
+
+/** Opens the Ink TUI. Every selection prints `reeve <command>` before running it. */
+export async function renderTui(io: ReeveIO): Promise<void> {
+  const instance = render(<ReeveTui io={io} />)
+  await instance.waitUntilExit()
+}