@remix-run/cli 0.0.0 → 0.1.0

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,157 @@
+import * as process from 'node:process'
+
+import { getCompletionCommandHelpText } from './completion.ts'
+import { renderCliError, toCliError, unknownHelpTopic } from '../errors.ts'
+import { formatHelpText } from '../help-text.ts'
+import { getDoctorCommandHelpText } from './doctor.ts'
+import { getNewCommandHelpText } from './new.ts'
+import { getRoutesCommandHelpText } from './routes.ts'
+import {
+  getSkillsCommandHelpText,
+  getSkillsInstallCommandHelpText,
+  getSkillsListCommandHelpText,
+} from './skills.ts'
+import { getTestCommandHelpText } from './test.ts'
+import { getVersionCommandHelpText } from './version.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(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: 'Manage Remix skills for the current project', label: 'skills' },
+        { 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 help skills install',
+        'remix doctor',
+        'remix new my-remix-app',
+        'remix new my-remix-app --app-name "My Remix App"',
+        'remix routes',
+        'remix skills install',
+        '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 skills install',
+        'remix help test',
+        'remix help version',
+      ],
+      usage: ['remix help [command]'],
+    },
+    target,
+  )
+}
+
+function getCommandHelpText(argv: string[]): 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) {
+    return getNewCommandHelpText()
+  }
+
+  if (command === 'completion' && rest.length === 0) {
+    return getCompletionCommandHelpText()
+  }
+
+  if (command === 'doctor' && rest.length === 0) {
+    return getDoctorCommandHelpText()
+  }
+
+  if (command === 'routes' && rest.length === 0) {
+    return getRoutesCommandHelpText()
+  }
+
+  if (command === 'skills') {
+    return getSkillsHelpText(rest)
+  }
+
+  if (command === 'test' && rest.length === 0) {
+    return getTestCommandHelpText()
+  }
+
+  if (command === 'version' && rest.length === 0) {
+    return getVersionCommandHelpText()
+  }
+
+  throw unknownHelpTopic(argv.join(' '))
+}
+
+function getNestedHelpText(command: string, argv: string[]): string {
+  throw unknownHelpTopic(`${command} ${argv.join(' ')}`)
+}
+
+function getSkillsHelpText(argv: string[]): string {
+  if (argv.length === 0) {
+    return getSkillsCommandHelpText()
+  }
+
+  let [subcommand, ...rest] = argv
+  if (rest.length > 0) {
+    throw unknownHelpTopic(`skills ${argv.join(' ')}`)
+  }
+
+  if (subcommand === 'install') {
+    return getSkillsInstallCommandHelpText()
+  }
+
+  if (subcommand === 'list') {
+    return getSkillsListCommandHelpText()
+  }
+
+  throw unknownHelpTopic(`skills ${argv.join(' ')}`)
+}

package/src/lib/commands/new.ts

@@ -0,0 +1,104 @@
+import * as process from 'node:process'
+
+import type {
+  BootstrapProjectOptions,
+  BootstrapProjectPhase,
+  BootstrapProgressReporter,
+} from '../bootstrap-project.ts'
+import { bootstrapProject } from '../bootstrap-project.ts'
+import type { CliContext } from '../cli-context.ts'
+import { renderCliError, missingTargetDirectory, toCliError } from '../errors.ts'
+import { getDisplayPath } from '../display-path.ts'
+import { formatHelpText } from '../help-text.ts'
+import { parseArgs } from '../parse-args.ts'
+import {
+  createCommandReporter,
+  createStepProgressReporter,
+  type CommandReporter,
+} from '../reporter.ts'
+
+const NEW_PROGRESS_LABELS = {
+  'finalize-package-json': 'Finalize package.json',
+  'generate-scaffold-files': 'Generate scaffold files',
+  'prepare-target-directory': 'Prepare target directory',
+} satisfies Record<BootstrapProjectPhase, string>
+
+export async function runNewCommand(argv: string[], context: CliContext): Promise<number> {
+  if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(getNewCommandHelpText())
+    return 0
+  }
+
+  let reporter: CommandReporter | null = null
+  let progress: BootstrapProgressReporter | null = null
+
+  try {
+    let options = parseNewCommandArgs(argv)
+    reporter = createCommandReporter({ remixVersion: context.remixVersion })
+    progress = createNewProgressReporter(reporter)
+
+    await reporter.status.commandHeader('new')
+    let result = await bootstrapProject(
+      {
+        ...options,
+        cwd: context.cwd,
+        remixVersion: context.remixVersion,
+      },
+      progress,
+    )
+    progress.writeSummaryGap()
+    reporter.out.line(
+      `Created ${result.appDisplayName} at ${getDisplayPath(result.targetDir, context.cwd)}`,
+    )
+    reporter.finish()
+    return 0
+  } catch (error) {
+    progress?.writeSummaryGap()
+    process.stderr.write(
+      renderCliError(toCliError(error), { helpText: getNewCommandHelpText(process.stderr) }),
+    )
+    reporter?.finish()
+    return 1
+  }
+}
+
+export function getNewCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return formatHelpText(
+    {
+      description: 'Create a new Remix project in the target directory.',
+      examples: [
+        'remix new ./my-remix-app',
+        'remix new ./my-remix-app --app-name "My Remix App"',
+        'remix new ./my-remix-app --force',
+      ],
+      usage: ['remix new <target-dir> [--app-name <name>] [--force]'],
+    },
+    target,
+  )
+}
+
+function parseNewCommandArgs(argv: string[]): BootstrapProjectOptions {
+  let parsed = parseArgs(
+    argv,
+    {
+      appName: { flag: '--app-name', type: 'string' },
+      force: { flag: '--force', type: 'boolean' },
+    },
+    { maxPositionals: 1 },
+  )
+  let targetDir = parsed.positionals[0] ?? null
+
+  if (targetDir == null) {
+    throw missingTargetDirectory()
+  }
+
+  return {
+    appName: parsed.options.appName ?? null,
+    force: parsed.options.force,
+    targetDir,
+  }
+}
+
+function createNewProgressReporter(reporter: CommandReporter): BootstrapProgressReporter {
+  return createStepProgressReporter(reporter.status, NEW_PROGRESS_LABELS)
+}