@remix-run/cli 0.0.0 → 0.1.0

package/package.json

@@ -1,14 +1,57 @@
 {
   "name": "@remix-run/cli",
-  "version": "0.0.0",
-  "description": "Placeholder package for Remix CI/OIDC setup",
+  "version": "0.1.0",
+  "description": "Command-line interface for Remix",
+  "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/remix-run/remix.git",
     "directory": "packages/cli"
   },
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/remix-run/remix/tree/main/packages/cli#readme",
+  "files": [
+    "bootstrap",
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=24.3.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "semver": "^7.7.4",
+    "@remix-run/test": "^0.2.0",
+    "@remix-run/tar-parser": "^0.7.1",
+    "@remix-run/terminal": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@types/semver": "^7.5.8",
+    "@typescript/native-preview": "7.0.0-dev.20251125.1",
+    "@remix-run/assert": "^0.1.0"
+  },
+  "keywords": [
+    "remix",
+    "cli",
+    "scaffold",
+    "project",
+    "command-line"
+  ],
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "clean": "git clean -fdX",
+    "test": "remix-test --concurrency 1",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { runRemix, type RunRemixOptions } from './lib/cli.ts'

package/src/lib/bootstrap-project.ts

@@ -0,0 +1,222 @@
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import * as process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import semver from 'semver'
+
+import {
+  appNameUnavailable,
+  invalidPackageName,
+  targetDirectoryNotEmpty,
+  targetPathNotDirectory,
+} 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'])
+export const MINIMUM_SUPPORTED_NODE_VERSION = '24.3.0'
+
+export interface BootstrapProjectOptions {
+  appName: string | null
+  cwd?: string
+  force: boolean
+  remixVersion?: string
+  targetDir: string
+}
+
+export type BootstrapProjectPhase =
+  | 'prepare-target-directory'
+  | 'generate-scaffold-files'
+  | 'finalize-package-json'
+
+export interface BootstrappedProject {
+  appDisplayName: string
+  targetDir: string
+}
+
+export type BootstrapProgressReporter = StepProgressReporter<BootstrapProjectPhase>
+
+interface BootstrapConfig {
+  appDisplayName: string
+  packageName: string
+  remixVersion: string
+}
+
+type TemplateValues = Record<string, string>
+
+export async function bootstrapProject(
+  options: BootstrapProjectOptions,
+  progress?: BootstrapProgressReporter,
+): Promise<BootstrappedProject> {
+  let cwd = options.cwd ?? process.cwd()
+  let targetDir = path.resolve(cwd, options.targetDir)
+  let rawAppName = options.appName ?? path.basename(targetDir)
+  if (rawAppName.length === 0) {
+    throw appNameUnavailable(targetDir)
+  }
+
+  let config = {
+    appDisplayName: options.appName ?? humanizeName(rawAppName),
+    packageName: toPackageName(rawAppName),
+    remixVersion: readDefaultRemixVersion(options.remixVersion),
+  } satisfies BootstrapConfig
+
+  await runProgressStep(progress, 'prepare-target-directory', () =>
+    ensureTargetDirectory(targetDir, options.force),
+  )
+  await runProgressStep(progress, 'generate-scaffold-files', () =>
+    copyBootstrapDirectory({
+      sourceDir: BOOTSTRAP_DIRECTORY,
+      targetDir,
+      templateValues: createTemplateValues(config),
+    }),
+  )
+  await runProgressStep(progress, 'finalize-package-json', () =>
+    writeScaffoldPackageJson(targetDir, config),
+  )
+
+  return {
+    appDisplayName: config.appDisplayName,
+    targetDir,
+  }
+}
+
+function readDefaultRemixVersion(runtimeVersion: string | undefined): string {
+  let overriddenVersion = process.env.REMIX_VERSION?.trim()
+  if (overriddenVersion) {
+    return overriddenVersion
+  }
+
+  if (runtimeVersion == null) {
+    return 'latest'
+  }
+
+  let validRuntimeVersion = semver.valid(runtimeVersion)
+  return validRuntimeVersion == null ? runtimeVersion : `^${validRuntimeVersion}`
+}
+
+function createTemplateValues(config: BootstrapConfig): TemplateValues {
+  return {
+    '%%RMX_APP_DISPLAY_NAME%%': config.appDisplayName,
+    '%%RMX_APP_DISPLAY_NAME_URI_COMPONENT%%': encodeURIComponent(config.appDisplayName),
+  }
+}
+
+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 {
+    dependencies?: Record<string, string>
+    devDependencies?: Record<string, string>
+    engines?: Record<string, string>
+    name?: string
+  }
+
+  packageJson.name = config.packageName
+  packageJson.dependencies = {
+    ...packageJson.dependencies,
+    remix: config.remixVersion,
+    tsx: 'latest',
+  }
+  packageJson.devDependencies = {
+    ...packageJson.devDependencies,
+    '@types/node': 'latest',
+    typescript: 'latest',
+  }
+  packageJson.engines = {
+    ...packageJson.engines,
+    node: `>=${MINIMUM_SUPPORTED_NODE_VERSION}`,
+  }
+
+  await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n', 'utf8')
+}
+
+async function ensureTargetDirectory(targetDir: string, force: boolean): Promise<void> {
+  try {
+    let stats = await fs.stat(targetDir)
+    if (!stats.isDirectory()) {
+      throw targetPathNotDirectory(targetDir)
+    }
+
+    let entries = await fs.readdir(targetDir)
+    if (entries.length > 0 && !force) {
+      throw targetDirectoryNotEmpty(targetDir)
+    }
+  } catch (error) {
+    let nodeError = error as NodeJS.ErrnoException
+    if (nodeError.code !== 'ENOENT') {
+      throw error
+    }
+  }
+
+  await fs.mkdir(targetDir, { recursive: true })
+}
+
+async function copyBootstrapDirectory({
+  sourceDir,
+  targetDir,
+  templateValues,
+}: {
+  sourceDir: string
+  targetDir: string
+  templateValues: TemplateValues
+}): Promise<void> {
+  let entries = await fs.readdir(sourceDir, { withFileTypes: true })
+
+  for (let entry of entries) {
+    let sourcePath = path.join(sourceDir, entry.name)
+    let targetPath = path.join(targetDir, entry.name)
+
+    if (BOOTSTRAP_EXCLUDED_NAMES.has(entry.name)) {
+      continue
+    }
+
+    if (entry.isDirectory()) {
+      await fs.mkdir(targetPath, { recursive: true })
+      await copyBootstrapDirectory({ sourceDir: sourcePath, targetDir: targetPath, templateValues })
+      continue
+    }
+
+    let content = await fs.readFile(sourcePath, 'utf8')
+    await fs.writeFile(targetPath, replaceTemplateValues(content, templateValues), 'utf8')
+  }
+}
+
+function replaceTemplateValues(content: string, templateValues: TemplateValues): string {
+  for (let [token, value] of Object.entries(templateValues)) {
+    content = content.split(token).join(value)
+  }
+
+  return content
+}
+
+function humanizeName(value: string): string {
+  let parts = value.split(/[-_\s]+/).filter(Boolean)
+  if (parts.length === 0) {
+    return 'Remix App'
+  }
+
+  return parts
+    .map((part) => {
+      let head = part.slice(0, 1).toUpperCase()
+      let tail = part.slice(1)
+      return `${head}${tail}`
+    })
+    .join(' ')
+}
+
+function toPackageName(value: string): string {
+  let packageName = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  if (packageName.length === 0) {
+    throw invalidPackageName(value)
+  }
+
+  return packageName
+}

package/src/lib/cli-context.ts

@@ -0,0 +1,38 @@
+import * as path from 'node:path'
+import * as process from 'node:process'
+
+import { resolveDefaultRemixVersion } from './remix-version.ts'
+
+interface ResolveCliContextOptions {
+  cwd?: string
+  remixVersion?: string
+}
+
+export interface CliContext {
+  cwd: string
+  remixVersion?: string
+}
+
+export async function resolveCliContext(
+  options: ResolveCliContextOptions = {},
+): Promise<CliContext> {
+  let cwd = resolveCwd(options.cwd)
+  let remixVersion = normalizeRemixVersion(options.remixVersion)
+
+  return {
+    cwd,
+    remixVersion: remixVersion ?? (await resolveDefaultRemixVersion(cwd)),
+  }
+}
+
+function resolveCwd(cwd: string | undefined): string {
+  let normalizedCwd = cwd?.trim()
+  return path.resolve(
+    normalizedCwd == null || normalizedCwd.length === 0 ? process.cwd() : normalizedCwd,
+  )
+}
+
+function normalizeRemixVersion(remixVersion: string | undefined): string | undefined {
+  let normalizedVersion = remixVersion?.trim()
+  return normalizedVersion == null || normalizedVersion.length === 0 ? undefined : normalizedVersion
+}

package/src/lib/cli.ts

@@ -0,0 +1,120 @@
+import * as process from 'node:process'
+
+import { runCompletionCommand } from './commands/completion.ts'
+import { runDoctorCommand } from './commands/doctor.ts'
+import { getCliHelpText, runHelpCommand } from './commands/help.ts'
+import { runNewCommand } from './commands/new.ts'
+import { runRoutesCommand } from './commands/routes.ts'
+import { runSkillsCommand } from './commands/skills.ts'
+import { runTestCommand } from './commands/test.ts'
+import { runVersionCommand } from './commands/version.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') {
+    return runVersionCommand([], context)
+  }
+
+  if (command === 'new') {
+    return runNewCommand(argv, context)
+  }
+
+  if (command === 'completion') {
+    return runCompletionCommand(argv)
+  }
+
+  if (command === 'doctor') {
+    return runDoctorCommand(argv, context)
+  }
+
+  if (command === 'skills') {
+    return runSkillsCommand(argv, context)
+  }
+
+  if (command === 'routes') {
+    return runRoutesCommand(argv, context)
+  }
+
+  if (command === 'test') {
+    return runTestCommand(argv, context)
+  }
+
+  if (command === 'version') {
+    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
+  }
+}