@remix-run/cli 0.0.0 → 0.2.0

package/src/lib/cli.ts

@@ -0,0 +1,116 @@
+import * as process from 'node:process'
+
+import { getCliHelpText, runHelpCommand } from './commands/help.ts'
+import { resolveCliContext, type CliContext } from './cli-context.ts'
+import { renderCliError, unknownCommand } from './errors.ts'
+import { configureColors, restoreTerminalFormatting } from './terminal.ts'
+
+export interface RunRemixOptions {
+  cwd?: string
+  remixVersion?: string
+}
+
+export async function runRemix(
+  argv: string[] = process.argv.slice(2),
+  options: RunRemixOptions = {},
+): Promise<number> {
+  let context = await resolveCliContext(options)
+
+  try {
+    while (argv[0] === '--') {
+      argv = argv.slice(1)
+    }
+
+    let globalOptions = extractGlobalOptions(argv)
+    argv = globalOptions.argv
+    configureColors({ disabled: globalOptions.noColor })
+
+    if (argv.length === 0) {
+      process.stdout.write(getCliHelpText())
+      return 0
+    }
+
+    let [command, ...rest] = argv
+
+    if (command === '-h' || command === '--help') {
+      process.stdout.write(getCliHelpText())
+      return 0
+    }
+
+    return await runCommand(command, rest, context)
+  } finally {
+    restoreTerminalFormatting()
+  }
+}
+
+async function runCommand(command: string, argv: string[], context: CliContext): Promise<number> {
+  if (command === 'help') {
+    return runHelpCommand(argv)
+  }
+
+  if (command === '-v' || command === '--version') {
+    let { runVersionCommand } = await import('./commands/version.ts')
+    return runVersionCommand([], context)
+  }
+
+  if (command === 'new') {
+    let { runNewCommand } = await import('./commands/new.ts')
+    return runNewCommand(argv, context)
+  }
+
+  if (command === 'completion') {
+    let { runCompletionCommand } = await import('./commands/completion.ts')
+    return runCompletionCommand(argv)
+  }
+
+  if (command === 'doctor') {
+    let { runDoctorCommand } = await import('./commands/doctor.ts')
+    return runDoctorCommand(argv, context)
+  }
+
+  if (command === 'routes') {
+    let { runRoutesCommand } = await import('./commands/routes.ts')
+    return runRoutesCommand(argv, context)
+  }
+
+  if (command === 'test') {
+    let { runTestCommand } = await import('./commands/test.ts')
+    return runTestCommand(argv, context)
+  }
+
+  if (command === 'version') {
+    let { runVersionCommand } = await import('./commands/version.ts')
+    return runVersionCommand(argv, context)
+  }
+
+  process.stderr.write(
+    renderCliError(unknownCommand(command), { helpText: getCliHelpText(process.stderr) }),
+  )
+  return 1
+}
+
+function extractGlobalOptions(argv: string[]): { argv: string[]; noColor: boolean } {
+  let filteredArgv: string[] = []
+  let noColor = false
+
+  for (let index = 0; index < argv.length; index++) {
+    let arg = argv[index]!
+
+    if (arg === '--') {
+      filteredArgv.push(...argv.slice(index))
+      break
+    }
+
+    if (arg === '--no-color') {
+      noColor = true
+      continue
+    }
+
+    filteredArgv.push(arg)
+  }
+
+  return {
+    argv: filteredArgv,
+    noColor,
+  }
+}

package/src/lib/commands/completion.ts

@@ -0,0 +1,74 @@
+import * as process from 'node:process'
+
+import {
+  getCompletionResult,
+  getCompletionScript,
+  isCompletionShell,
+  renderCompletionResult,
+} from '../completion.ts'
+import {
+  invalidCompletionRequest,
+  renderCliError,
+  toCliError,
+  unknownCompletionShell,
+} from '../errors.ts'
+import { formatHelpText } from '../help-text.ts'
+import { parseArgs } from '../parse-args.ts'
+
+export async function runCompletionCommand(argv: string[]): Promise<number> {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    process.stdout.write(getCompletionCommandHelpText())
+    return 0
+  }
+
+  if (argv[0] === '--') {
+    return runCompletionPlumbing(argv.slice(1))
+  }
+
+  let [shell, ...rest] = argv
+
+  try {
+    parseArgs(rest, {}, { maxPositionals: 0 })
+
+    if (!isCompletionShell(shell)) {
+      throw unknownCompletionShell(shell)
+    }
+
+    process.stdout.write(getCompletionScript())
+    return 0
+  } catch (error) {
+    process.stderr.write(
+      renderCliError(toCliError(error), {
+        helpText: getCompletionCommandHelpText(process.stderr),
+      }),
+    )
+    return 1
+  }
+}
+
+export function getCompletionCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return formatHelpText(
+    {
+      description: 'Print a shell completion script for Remix.',
+      examples: ['remix completion bash >> ~/.bashrc', 'remix completion zsh >> ~/.zshrc'],
+      usage: ['remix completion <bash|zsh>'],
+    },
+    target,
+  )
+}
+
+function runCompletionPlumbing(argv: string[]): number {
+  try {
+    let [currentIndexArg, ...words] = argv
+    if (currentIndexArg == null || !/^\d+$/.test(currentIndexArg)) {
+      throw invalidCompletionRequest()
+    }
+
+    let currentIndex = Number(currentIndexArg)
+    process.stdout.write(renderCompletionResult(getCompletionResult(words, currentIndex)))
+    return 0
+  } catch (error) {
+    process.stderr.write(renderCliError(toCliError(error)))
+    return 1
+  }
+}

package/src/lib/commands/doctor.ts

@@ -0,0 +1,393 @@
+import * as path from 'node:path'
+import * as process from 'node:process'
+
+import { checkControllerConventions } from '../doctor/controllers.ts'
+import type { CliContext } from '../cli-context.ts'
+import { checkEnvironment, getEnvironmentFixPlans } from '../doctor/environment.ts'
+import { applyDoctorFixPlans } from '../doctor/fixes.ts'
+import { checkProject, getProjectFixPlans } from '../doctor/project.ts'
+import {
+  createDoctorSuite,
+  createSkippedDoctorSuite,
+  type DoctorAppliedFix,
+  type DoctorFinding,
+  type DoctorReport,
+  type DoctorSuiteName,
+  type DoctorSuiteResult,
+} from '../doctor/types.ts'
+import { renderCliError, toCliError } from '../errors.ts'
+import { formatHelpText } from '../help-text.ts'
+import { parseArgs } from '../parse-args.ts'
+import {
+  createCommandReporter,
+  createStepProgressReporter,
+  type CommandReporter,
+  type StepProgressReporter,
+} from '../reporter.ts'
+
+const DOCTOR_SUITE_LABELS = {
+  controllers: {
+    complete: 'controllers',
+    running: 'Checking controllers',
+  },
+  environment: {
+    complete: 'environment',
+    running: 'Checking environment',
+  },
+  project: {
+    complete: 'project',
+    running: 'Checking project',
+  },
+} satisfies Record<DoctorSuiteName, string | { complete: string; running: string }>
+
+interface DoctorCommandOptions {
+  fix: boolean
+  json: boolean
+  strict: boolean
+}
+
+export async function runDoctorCommand(argv: string[], context: CliContext): Promise<number> {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(getDoctorCommandHelpText())
+    return 0
+  }
+
+  let reporter: CommandReporter | null = null
+  let progress: StepProgressReporter<DoctorSuiteName> | null = null
+
+  try {
+    let options = parseDoctorCommandArgs(argv)
+    reporter = options.json
+      ? null
+      : createCommandReporter({
+          remixVersion: context.remixVersion,
+          stderr: process.stdout,
+          stdout: process.stdout,
+        })
+    progress = reporter == null ? null : createDoctorProgressReporter(reporter)
+    if (reporter != null) {
+      await reporter.status.commandHeader('doctor')
+    }
+
+    let report = await collectDoctorReport(progress, options, reporter, context)
+
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    } else if (reporter != null) {
+      writeDoctorReport(reporter, report)
+      reporter.finish()
+    }
+
+    if ((options.fix || options.strict) && hasWarningFindings(report.findings)) {
+      return 1
+    }
+
+    return 0
+  } catch (error) {
+    progress?.writeSummaryGap()
+    process.stderr.write(
+      renderCliError(toCliError(error), { helpText: getDoctorCommandHelpText(process.stderr) }),
+    )
+    reporter?.finish()
+    return 1
+  }
+}
+
+export function getDoctorCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return formatHelpText(
+    {
+      description: 'Check project environment and Remix app conventions for the current project.',
+      examples: [
+        'remix doctor',
+        'remix doctor --json',
+        'remix doctor --strict',
+        'remix doctor --fix',
+      ],
+      options: [
+        { description: 'Print doctor findings as JSON', label: '--json' },
+        {
+          description: 'Exit with status 1 when warning-level findings are present',
+          label: '--strict',
+        },
+        { description: 'Apply low-risk project and controller fixes', label: '--fix' },
+      ],
+      usage: ['remix doctor [--json] [--strict] [--fix] [--no-color]'],
+    },
+    target,
+  )
+}
+
+function parseDoctorCommandArgs(argv: string[]): DoctorCommandOptions {
+  let parsed = parseArgs(
+    argv,
+    {
+      fix: { flag: '--fix', type: 'boolean' },
+      json: { flag: '--json', type: 'boolean' },
+      strict: { flag: '--strict', type: 'boolean' },
+    },
+    { maxPositionals: 0 },
+  )
+
+  return {
+    fix: parsed.options.fix,
+    json: parsed.options.json,
+    strict: parsed.options.strict,
+  }
+}
+
+async function collectDoctorReport(
+  progress: StepProgressReporter<DoctorSuiteName> | null,
+  options: DoctorCommandOptions,
+  reporter: CommandReporter | null,
+  context: CliContext,
+): Promise<DoctorReport> {
+  let cwd = context.cwd
+  let appliedFixes: DoctorAppliedFix[] = []
+  let environment = await runDoctorSuite(progress, 'environment', async () => {
+    let result = await checkEnvironment(cwd)
+    let suiteAppliedFixes: DoctorAppliedFix[] = []
+    let finalResult = result
+
+    if (options.fix && result.projectRoot != null) {
+      let fixPlans = getEnvironmentFixPlans(result, context.remixVersion)
+      if (fixPlans.length > 0) {
+        suiteAppliedFixes = await applyDoctorFixPlans(result.projectRoot, fixPlans)
+        finalResult = await checkEnvironment(result.projectRoot)
+      }
+    }
+
+    let suite = finalResult.suite
+    if (suiteAppliedFixes.length > 0) {
+      suite = {
+        ...suite,
+        appliedFixes: suiteAppliedFixes,
+      }
+    }
+
+    return {
+      appliedFixes: suiteAppliedFixes,
+      projectRoot: finalResult.projectRoot ?? result.projectRoot,
+      suite,
+    }
+  })
+  let findings = [...environment.suite.findings]
+  appliedFixes.push(...(environment.appliedFixes ?? []))
+  let suites: DoctorSuiteResult[] = [environment.suite]
+  let routesFile =
+    environment.projectRoot == null
+      ? undefined
+      : path.join(environment.projectRoot, 'app', 'routes.ts')
+  writeDoctorSuiteDetails(reporter, environment.suite)
+  progress?.writeSummaryGap()
+
+  if (hasWarningFindings(environment.suite.findings)) {
+    let projectSuite = createSkippedDoctorSuite('project', 'Blocked by environment warnings.')
+    let controllersSuite = createSkippedDoctorSuite(
+      'controllers',
+      'Blocked by environment warnings.',
+    )
+    suites.push(projectSuite, controllersSuite)
+    progress?.skip(projectSuite.name, projectSuite.reason)
+    writeDoctorSuiteDetails(reporter, projectSuite)
+    progress?.writeSummaryGap()
+    progress?.skip(controllersSuite.name, controllersSuite.reason)
+    writeDoctorSuiteDetails(reporter, controllersSuite)
+    progress?.writeSummaryGap()
+
+    return {
+      appRoot: environment.projectRoot,
+      appliedFixes,
+      findings,
+      remainingFindings: findings,
+      routesFile,
+      suites,
+    }
+  }
+
+  let project = await runDoctorSuite(progress, 'project', async () => {
+    let result = await checkProject(environment.projectRoot!)
+    let suiteAppliedFixes: DoctorAppliedFix[] = []
+    let finalResult = result
+
+    if (options.fix) {
+      let fixPlans = await getProjectFixPlans(environment.projectRoot!)
+      if (fixPlans.length > 0) {
+        suiteAppliedFixes = await applyDoctorFixPlans(environment.projectRoot!, fixPlans)
+        finalResult = await checkProject(environment.projectRoot!)
+      }
+    }
+
+    let suite = finalResult.suite
+    if (suiteAppliedFixes.length > 0) {
+      suite = {
+        ...suite,
+        appliedFixes: suiteAppliedFixes,
+      }
+    }
+
+    return {
+      appliedFixes: suiteAppliedFixes,
+      routeManifest: finalResult.routeManifest,
+      routesFile: finalResult.routesFile,
+      suite,
+    }
+  })
+  findings.push(...project.suite.findings)
+  appliedFixes.push(...(project.appliedFixes ?? []))
+  routesFile = project.routesFile
+  suites.push(project.suite)
+  writeDoctorSuiteDetails(reporter, project.suite)
+  progress?.writeSummaryGap()
+
+  if (hasWarningFindings(project.suite.findings)) {
+    let controllersSuite = createSkippedDoctorSuite('controllers', 'Blocked by project warnings.')
+    suites.push(controllersSuite)
+    progress?.skip(controllersSuite.name, controllersSuite.reason)
+    writeDoctorSuiteDetails(reporter, controllersSuite)
+    progress?.writeSummaryGap()
+
+    return {
+      appRoot: environment.projectRoot,
+      appliedFixes,
+      findings,
+      remainingFindings: findings,
+      routesFile,
+      suites,
+    }
+  }
+
+  let controllers = await runDoctorSuite(progress, 'controllers', async () => {
+    let controllerResult = await checkControllerConventions(
+      project.routeManifest!.appRoot,
+      project.routeManifest!.tree,
+    )
+    let remainingFindings = controllerResult.suite.findings
+    let suiteAppliedFixes: DoctorAppliedFix[] = []
+
+    if (options.fix && controllerResult.fixPlans.length > 0) {
+      suiteAppliedFixes = await applyDoctorFixPlans(
+        project.routeManifest!.appRoot,
+        controllerResult.fixPlans,
+      )
+      let finalControllerResult = await checkControllerConventions(
+        project.routeManifest!.appRoot,
+        project.routeManifest!.tree,
+      )
+      remainingFindings = finalControllerResult.suite.findings
+    }
+
+    let suite = createDoctorSuite('controllers', remainingFindings)
+    if (suiteAppliedFixes.length > 0) {
+      suite.appliedFixes = suiteAppliedFixes
+    }
+
+    return { appliedFixes: suiteAppliedFixes, suite }
+  })
+
+  findings.push(...controllers.suite.findings)
+  appliedFixes.push(...(controllers.appliedFixes ?? []))
+  suites.push(controllers.suite)
+  writeDoctorSuiteDetails(reporter, controllers.suite)
+  progress?.writeSummaryGap()
+
+  let report: DoctorReport = {
+    appRoot: environment.projectRoot,
+    findings,
+    routesFile,
+    suites,
+  }
+
+  if (options.fix) {
+    report.appliedFixes = appliedFixes
+    report.remainingFindings = findings
+  }
+
+  return report
+}
+
+function hasWarningFindings(findings: DoctorFinding[]): boolean {
+  return findings.some((finding) => finding.severity === 'warn')
+}
+
+function formatAppliedFix(appliedFix: DoctorAppliedFix): string {
+  if (appliedFix.kind === 'update-file') {
+    return `Updated ${appliedFix.path}`
+  }
+
+  return `Created ${appliedFix.path}`
+}
+
+async function runDoctorSuite<
+  result extends { appliedFixes?: DoctorAppliedFix[]; suite: DoctorSuiteResult },
+>(
+  progress: StepProgressReporter<DoctorSuiteName> | null,
+  label: DoctorSuiteName,
+  callback: () => Promise<result>,
+): Promise<result> {
+  progress?.start(label)
+
+  try {
+    let result = await callback()
+
+    if (result.suite.status === 'ok') {
+      progress?.succeed(label)
+    } else if (result.suite.status === 'issues') {
+      progress?.fail(label)
+    } else {
+      progress?.skip(label, result.suite.reason)
+    }
+
+    return result
+  } catch (error) {
+    progress?.fail(label)
+    throw error
+  }
+}
+
+function createDoctorProgressReporter(
+  reporter: CommandReporter,
+): StepProgressReporter<DoctorSuiteName> {
+  return createStepProgressReporter(reporter.status, DOCTOR_SUITE_LABELS)
+}
+
+function writeDoctorReport(reporter: CommandReporter, report: DoctorReport): void {
+  let warningCount = report.findings.filter((finding) => finding.severity === 'warn').length
+  let adviceCount = report.findings.length - warningCount
+
+  if ((report.appliedFixes?.length ?? 0) > 0) {
+    let fixCount = report.appliedFixes!.length
+    reporter.out.line(`Applied ${fixCount} ${fixCount === 1 ? 'fix' : 'fixes'}.`)
+  }
+
+  if (report.findings.length === 0) {
+    reporter.out.line('Doctor found no issues.')
+  }
+
+  reporter.out.line(`Summary: ${warningCount} warnings, ${adviceCount} advice.`)
+}
+
+function writeDoctorSuiteDetails(reporter: CommandReporter | null, suite: DoctorSuiteResult): void {
+  if (reporter == null) {
+    return
+  }
+
+  if (suite.findings.length === 0 && (suite.appliedFixes?.length ?? 0) === 0) {
+    return
+  }
+
+  reporter.out.withIndent(() => {
+    for (let finding of suite.findings) {
+      reporter.out.bullet(
+        reporter.out.label(finding.severity.toUpperCase(), finding.message, {
+          tone: finding.severity === 'warn' ? 'warn' : undefined,
+        }),
+      )
+    }
+
+    if ((suite.appliedFixes?.length ?? 0) > 0) {
+      reporter.out.section('Applied fixes:', () => {
+        reporter.out.bullets((suite.appliedFixes ?? []).map(formatAppliedFix))
+      })
+    }
+  })
+}

package/src/lib/commands/help.ts

@@ -0,0 +1,123 @@
+import * as process from 'node:process'
+
+import { renderCliError, toCliError, unknownHelpTopic } from '../errors.ts'
+import { formatHelpText } from '../help-text.ts'
+
+export async function runHelpCommand(argv: string[]): Promise<number> {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(getHelpCommandHelpText())
+    return 0
+  }
+
+  try {
+    process.stdout.write(await getCommandHelpText(argv))
+    return 0
+  } catch (error) {
+    process.stderr.write(
+      renderCliError(toCliError(error), { helpText: getCliHelpText(process.stderr) }),
+    )
+    return 1
+  }
+}
+
+export function getCliHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return formatHelpText(
+    {
+      commands: [
+        { description: 'Print shell completion scripts for Remix', label: 'completion' },
+        { description: 'Show help for Remix commands', label: 'help [command]' },
+        { description: 'Create a new Remix project', label: 'new <name>' },
+        { description: 'Check project health for the current project', label: 'doctor' },
+        { description: 'Show the route tree for the current project', label: 'routes' },
+        { description: 'Run tests for the current project', label: 'test [glob]' },
+        { description: 'Show the current Remix version', label: 'version' },
+      ],
+      examples: [
+        'remix completion bash',
+        'remix help',
+        'remix help completion',
+        'remix help doctor',
+        'remix doctor',
+        'remix new my-remix-app',
+        'remix new my-remix-app --app-name "My Remix App"',
+        'remix routes',
+        'remix test',
+        'remix version',
+      ],
+      options: [
+        { description: 'Show help', label: '-h, --help' },
+        { description: 'Disable ANSI color output', label: '--no-color' },
+        { description: 'Show version', label: '-v, --version' },
+      ],
+      usage: ['remix <command> [options]'],
+    },
+    target,
+  )
+}
+
+export function getHelpCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return formatHelpText(
+    {
+      description: 'Show help for Remix commands.',
+      examples: [
+        'remix help',
+        'remix help completion',
+        'remix help doctor',
+        'remix help new',
+        'remix help routes',
+        'remix help test',
+        'remix help version',
+      ],
+      usage: ['remix help [command]'],
+    },
+    target,
+  )
+}
+
+async function getCommandHelpText(argv: string[]): Promise<string> {
+  if (argv.length === 0) {
+    return getCliHelpText()
+  }
+
+  let [command, ...rest] = argv
+
+  if (command === 'help') {
+    return rest.length === 0 ? getHelpCommandHelpText() : getNestedHelpText(command, rest)
+  }
+
+  if (command === 'new' && rest.length === 0) {
+    let { getNewCommandHelpText } = await import('./new.ts')
+    return getNewCommandHelpText()
+  }
+
+  if (command === 'completion' && rest.length === 0) {
+    let { getCompletionCommandHelpText } = await import('./completion.ts')
+    return getCompletionCommandHelpText()
+  }
+
+  if (command === 'doctor' && rest.length === 0) {
+    let { getDoctorCommandHelpText } = await import('./doctor.ts')
+    return getDoctorCommandHelpText()
+  }
+
+  if (command === 'routes' && rest.length === 0) {
+    let { getRoutesCommandHelpText } = await import('./routes.ts')
+    return getRoutesCommandHelpText()
+  }
+
+  if (command === 'test' && rest.length === 0) {
+    let { getTestCommandHelpText } = await import('./test.ts')
+    return await getTestCommandHelpText()
+  }
+
+  if (command === 'version' && rest.length === 0) {
+    let { getVersionCommandHelpText } = await import('./version.ts')
+    return getVersionCommandHelpText()
+  }
+
+  throw unknownHelpTopic(argv.join(' '))
+}
+
+function getNestedHelpText(command: string, argv: string[]): string {
+  throw unknownHelpTopic(`${command} ${argv.join(' ')}`)
+}