@remix-run/cli 0.2.0 → 0.3.0

package/src/lib/bootstrap-project.ts

@@ -12,11 +12,10 @@ import {
 } from './errors.ts'
 import { runProgressStep, type StepProgressReporter } from './reporter.ts'
 
-const BOOTSTRAP_DIRECTORY = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  '../../bootstrap',
-)
-const BOOTSTRAP_EXCLUDED_NAMES = new Set(['.gitkeep', 'node_modules'])
+const MODULE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url))
+const PACKAGE_TEMPLATE_DIRECTORY = path.resolve(MODULE_DIRECTORY, '../../template')
+const REPO_TEMPLATE_DIRECTORY = path.resolve(MODULE_DIRECTORY, '../../../../template')
+const TEMPLATE_EXCLUDED_NAMES = new Set(['.gitkeep', 'node_modules'])
 export const MINIMUM_SUPPORTED_NODE_VERSION = '24.3.0'
 
 export interface BootstrapProjectOptions {
@@ -67,9 +66,9 @@ export async function bootstrapProject(
   await runProgressStep(progress, 'prepare-target-directory', () =>
     ensureTargetDirectory(targetDir, options.force),
   )
-  await runProgressStep(progress, 'generate-scaffold-files', () =>
-    copyBootstrapDirectory({
-      sourceDir: BOOTSTRAP_DIRECTORY,
+  await runProgressStep(progress, 'generate-scaffold-files', async () =>
+    copyTemplateDirectory({
+      sourceDir: await resolveTemplateDirectory(),
       targetDir,
       templateValues: createTemplateValues(config),
     }),
@@ -105,6 +104,34 @@ function createTemplateValues(config: BootstrapConfig): TemplateValues {
   }
 }
 
+async function resolveTemplateDirectory(): Promise<string> {
+  if (await isDirectory(PACKAGE_TEMPLATE_DIRECTORY)) {
+    return PACKAGE_TEMPLATE_DIRECTORY
+  }
+
+  if (await isDirectory(REPO_TEMPLATE_DIRECTORY)) {
+    return REPO_TEMPLATE_DIRECTORY
+  }
+
+  throw new Error(
+    `Could not find the Remix app template at ${PACKAGE_TEMPLATE_DIRECTORY} or ${REPO_TEMPLATE_DIRECTORY}.`,
+  )
+}
+
+async function isDirectory(directory: string): Promise<boolean> {
+  try {
+    let stats = await fs.stat(directory)
+    return stats.isDirectory()
+  } catch (error) {
+    let nodeError = error as NodeJS.ErrnoException
+    if (nodeError.code === 'ENOENT') {
+      return false
+    }
+
+    throw error
+  }
+}
+
 async function writeScaffoldPackageJson(targetDir: string, config: BootstrapConfig): Promise<void> {
   let packageJsonPath = path.join(targetDir, 'package.json')
   let packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8')) as {
@@ -118,7 +145,6 @@ async function writeScaffoldPackageJson(targetDir: string, config: BootstrapConf
   packageJson.dependencies = {
     ...packageJson.dependencies,
     remix: config.remixVersion,
-    tsx: 'latest',
   }
   packageJson.devDependencies = {
     ...packageJson.devDependencies,
@@ -154,7 +180,7 @@ async function ensureTargetDirectory(targetDir: string, force: boolean): Promise
   await fs.mkdir(targetDir, { recursive: true })
 }
 
-async function copyBootstrapDirectory({
+async function copyTemplateDirectory({
   sourceDir,
   targetDir,
   templateValues,
@@ -167,15 +193,15 @@ async function copyBootstrapDirectory({
 
   for (let entry of entries) {
     let sourcePath = path.join(sourceDir, entry.name)
-    let targetPath = path.join(targetDir, entry.name)
+    let targetPath = path.join(targetDir, entry.name === 'gitignore' ? '.gitignore' : entry.name)
 
-    if (BOOTSTRAP_EXCLUDED_NAMES.has(entry.name)) {
+    if (TEMPLATE_EXCLUDED_NAMES.has(entry.name)) {
       continue
     }
 
     if (entry.isDirectory()) {
       await fs.mkdir(targetPath, { recursive: true })
-      await copyBootstrapDirectory({ sourceDir: sourcePath, targetDir: targetPath, templateValues })
+      await copyTemplateDirectory({ sourceDir: sourcePath, targetDir: targetPath, templateValues })
       continue
     }
 

package/src/lib/cli.ts

@@ -5,11 +5,40 @@ import { resolveCliContext, type CliContext } from './cli-context.ts'
 import { renderCliError, unknownCommand } from './errors.ts'
 import { configureColors, restoreTerminalFormatting } from './terminal.ts'
 
+/**
+ * Options accepted by {@link runRemix}.
+ */
 export interface RunRemixOptions {
+  /**
+   * Directory used as the working root when resolving project files (default
+   * `process.cwd()`).
+   */
   cwd?: string
+  /**
+   * Override for the Remix version reported by `remix --version`. Defaults to
+   * the version of the installed `@remix-run/cli` package.
+   */
   remixVersion?: string
 }
 
+/**
+ * Entry point for the `remix` CLI. Parses `argv`, dispatches to the matching
+ * subcommand (`new`, `doctor`, `routes`, `test`, `version`, `completion`,
+ * `help`), and resolves with the exit code the process should use.
+ *
+ * @param argv Argument vector to parse, excluding the node and script paths
+ *             (default `process.argv.slice(2)`).
+ * @param options Overrides for CLI context resolution.
+ * @returns The numeric exit code (`0` on success, non-zero on failure).
+ *
+ * @example
+ * ```ts
+ * import { runRemix } from '@remix-run/cli'
+ *
+ * let exitCode = await runRemix(process.argv.slice(2))
+ * process.exit(exitCode)
+ * ```
+ */
 export async function runRemix(
   argv: string[] = process.argv.slice(2),
   options: RunRemixOptions = {},
@@ -17,12 +46,10 @@ export async function runRemix(
   let context = await resolveCliContext(options)
 
   try {
-    while (argv[0] === '--') {
-      argv = argv.slice(1)
-    }
+    argv = stripLeadingSeparators(argv)
 
     let globalOptions = extractGlobalOptions(argv)
-    argv = globalOptions.argv
+    argv = stripLeadingSeparators(globalOptions.argv)
     configureColors({ disabled: globalOptions.noColor })
 
     if (argv.length === 0) {
@@ -43,6 +70,14 @@ export async function runRemix(
   }
 }
 
+function stripLeadingSeparators(argv: string[]): string[] {
+  while (argv[0] === '--') {
+    argv = argv.slice(1)
+  }
+
+  return argv
+}
+
 async function runCommand(command: string, argv: string[], context: CliContext): Promise<number> {
   if (command === 'help') {
     return runHelpCommand(argv)

package/src/lib/commands/completion.ts

@@ -16,7 +16,7 @@ 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') {
+  if (argv.length === 0) {
     process.stdout.write(getCompletionCommandHelpText())
     return 0
   }
@@ -25,6 +25,11 @@ export async function runCompletionCommand(argv: string[]): Promise<number> {
     return runCompletionPlumbing(argv.slice(1))
   }
 
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(getCompletionCommandHelpText())
+    return 0
+  }
+
   let [shell, ...rest] = argv
 
   try {

package/src/lib/commands/doctor.ts

@@ -26,9 +26,9 @@ import {
 } from '../reporter.ts'
 
 const DOCTOR_SUITE_LABELS = {
-  controllers: {
-    complete: 'controllers',
-    running: 'Checking controllers',
+  actions: {
+    complete: 'actions',
+    running: 'Checking actions',
   },
   environment: {
     complete: 'environment',
@@ -109,7 +109,7 @@ export function getDoctorCommandHelpText(target: NodeJS.WriteStream = process.st
           description: 'Exit with status 1 when warning-level findings are present',
           label: '--strict',
         },
-        { description: 'Apply low-risk project and controller fixes', label: '--fix' },
+        { description: 'Apply low-risk project and action fixes', label: '--fix' },
       ],
       usage: ['remix doctor [--json] [--strict] [--fix] [--no-color]'],
     },
@@ -182,16 +182,13 @@ async function collectDoctorReport(
 
   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)
+    let actionsSuite = createSkippedDoctorSuite('actions', 'Blocked by environment warnings.')
+    suites.push(projectSuite, actionsSuite)
     progress?.skip(projectSuite.name, projectSuite.reason)
     writeDoctorSuiteDetails(reporter, projectSuite)
     progress?.writeSummaryGap()
-    progress?.skip(controllersSuite.name, controllersSuite.reason)
-    writeDoctorSuiteDetails(reporter, controllersSuite)
+    progress?.skip(actionsSuite.name, actionsSuite.reason)
+    writeDoctorSuiteDetails(reporter, actionsSuite)
     progress?.writeSummaryGap()
 
     return {
@@ -240,10 +237,10 @@ async function collectDoctorReport(
   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)
+    let actionsSuite = createSkippedDoctorSuite('actions', 'Blocked by project warnings.')
+    suites.push(actionsSuite)
+    progress?.skip(actionsSuite.name, actionsSuite.reason)
+    writeDoctorSuiteDetails(reporter, actionsSuite)
     progress?.writeSummaryGap()
 
     return {
@@ -256,7 +253,7 @@ async function collectDoctorReport(
     }
   }
 
-  let controllers = await runDoctorSuite(progress, 'controllers', async () => {
+  let actions = await runDoctorSuite(progress, 'actions', async () => {
     let controllerResult = await checkControllerConventions(
       project.routeManifest!.appRoot,
       project.routeManifest!.tree,
@@ -276,7 +273,7 @@ async function collectDoctorReport(
       remainingFindings = finalControllerResult.suite.findings
     }
 
-    let suite = createDoctorSuite('controllers', remainingFindings)
+    let suite = createDoctorSuite('actions', remainingFindings)
     if (suiteAppliedFixes.length > 0) {
       suite.appliedFixes = suiteAppliedFixes
     }
@@ -284,10 +281,10 @@ async function collectDoctorReport(
     return { appliedFixes: suiteAppliedFixes, suite }
   })
 
-  findings.push(...controllers.suite.findings)
-  appliedFixes.push(...(controllers.appliedFixes ?? []))
-  suites.push(controllers.suite)
-  writeDoctorSuiteDetails(reporter, controllers.suite)
+  findings.push(...actions.suite.findings)
+  appliedFixes.push(...(actions.appliedFixes ?? []))
+  suites.push(actions.suite)
+  writeDoctorSuiteDetails(reporter, actions.suite)
   progress?.writeSummaryGap()
 
   let report: DoctorReport = {

package/src/lib/commands/routes.ts

@@ -8,7 +8,7 @@ import { createCommandReporter, type TextChannel } from '../reporter.ts'
 import { loadRouteMap, type LoadedRouteMap, type RouteTreeNode } from '../route-map.ts'
 import { lightRed } from '../terminal.ts'
 
-const CONTROLLERS_PATH_PREFIX = 'app/controllers/'
+const ACTIONS_PATH_PREFIX = 'app/actions/'
 
 export async function runRoutesCommand(argv: string[], context: CliContext): Promise<number> {
   if (argv.includes('-h') || argv.includes('--help')) {
@@ -243,8 +243,8 @@ function colorRouteLine(line: string, node: RouteTreeNode): string {
 }
 
 function getCompactOwnerPath(ownerPath: string): string {
-  if (ownerPath.startsWith(CONTROLLERS_PATH_PREFIX)) {
-    return ownerPath.slice(CONTROLLERS_PATH_PREFIX.length)
+  if (ownerPath.startsWith(ACTIONS_PATH_PREFIX)) {
+    return ownerPath.slice(ACTIONS_PATH_PREFIX.length)
   }
 
   return ownerPath

package/src/lib/completion.ts

@@ -169,11 +169,7 @@ function completeCommand(
   }
 
   if (command === 'test') {
-    return completeSimpleFlags(tokens, currentWord, usedGlobalFlags, [
-      '--coverage',
-      '--watch',
-      '--help',
-    ])
+    return completeSimpleFlags(tokens, currentWord, usedGlobalFlags, ['--coverage', '--watch'])
   }
 
   if (command === 'completion') {

package/src/lib/controller-files.ts

@@ -1,22 +1,18 @@
 import * as path from 'node:path'
 
 const OWNER_FILE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'] as const
-export type OwnerFileExtension = (typeof OWNER_FILE_EXTENSIONS)[number]
+const ACTIONS_DIRECTORY = path.join('app', 'actions')
 
-export function getActionOwnerCandidates(segments: string[]): string[] {
-  return OWNER_FILE_EXTENSIONS.map((extension) =>
-    normalizeRelativePath(path.join('app', 'controllers', `${path.join(...segments)}${extension}`)),
-  )
-}
+export type OwnerFileExtension = (typeof OWNER_FILE_EXTENSIONS)[number]
 
 export function getControllerOwnerCandidates(segments: string[]): string[] {
   return OWNER_FILE_EXTENSIONS.map((extension) =>
-    normalizeRelativePath(path.join('app', 'controllers', ...segments, `controller${extension}`)),
+    normalizeRelativePath(path.join(ACTIONS_DIRECTORY, ...segments, `controller${extension}`)),
   )
 }
 
 export function getRouteSubtreePath(segments: string[]): string {
-  return normalizeRelativePath(path.join('app', 'controllers', ...segments))
+  return normalizeRelativePath(path.join(ACTIONS_DIRECTORY, ...segments))
 }
 
 export function getPreferredOwnerDisplayPath(candidates: string[]): string {