@remix-run/cli 0.0.0 → 0.2.0

package/src/lib/errors.ts

@@ -0,0 +1,367 @@
+export interface CliErrorDefinition {
+  code: string
+  docsUrl?: string
+  fix?: string
+  title: string
+}
+
+export type CliErrorContext = Record<string, boolean | number | string | null | undefined>
+
+export interface CliErrorOptions {
+  code: string
+  context?: CliErrorContext
+  docsUrl?: string
+  fix?: string
+  message: string
+  showHelp?: boolean
+  title: string
+}
+
+interface CreateErrorOptions {
+  context?: CliErrorContext
+  message: string
+}
+
+export const CLI_ERROR_DEFINITIONS = {
+  appNameUnavailable: {
+    code: 'RMX_APP_NAME_UNAVAILABLE',
+    title: 'Could not determine an app name',
+    fix: 'Pass --app-name or choose a target directory name that can become an app name.',
+  },
+  remixVersionUnavailable: {
+    code: 'RMX_REMIX_VERSION_UNAVAILABLE',
+    title: 'Could not determine the Remix version',
+  },
+  invalidCompletionRequest: {
+    code: 'RMX_INVALID_COMPLETION_REQUEST',
+    title: 'Invalid completion request',
+  },
+  fetchUnavailable: {
+    code: 'RMX_FETCH_UNAVAILABLE',
+    title: 'This runtime does not provide fetch()',
+    fix: 'Run the Remix CLI in a runtime that provides fetch().',
+  },
+  internalError: {
+    code: 'RMX_INTERNAL_ERROR',
+    title: 'Unexpected Remix CLI error',
+  },
+  invalidFlagCombination: {
+    code: 'RMX_INVALID_FLAG_COMBINATION',
+    title: 'Invalid flag combination',
+    fix: 'Remove one of the conflicting flags and try again.',
+  },
+  invalidPackageName: {
+    code: 'RMX_INVALID_PACKAGE_NAME',
+    title: 'Could not derive a valid package name',
+    fix: 'Choose an app name that can be normalized into a valid npm package name.',
+  },
+  missingOptionValue: {
+    code: 'RMX_MISSING_OPTION_VALUE',
+    title: 'Missing option value',
+    fix: 'Pass a value immediately after the option.',
+  },
+  missingTargetDirectory: {
+    code: 'RMX_MISSING_TARGET_DIRECTORY',
+    title: 'Missing target directory',
+    fix: 'Pass a target directory, for example `remix new my-remix-app`.',
+  },
+  projectRootNotFound: {
+    code: 'RMX_PROJECT_ROOT_NOT_FOUND',
+    title: 'Could not find a project root',
+    fix: 'Run this command inside a Remix project.',
+  },
+  remoteSkillDataMissing: {
+    code: 'RMX_REMOTE_SKILL_DATA_MISSING',
+    title: 'Could not find remote Remix skill data',
+  },
+  routeMapLoaderFailed: {
+    code: 'RMX_ROUTE_MAP_LOADER_FAILED',
+    title: 'Route-map loader failed',
+    fix: 'Check app/routes.ts and make sure it exports a named `routes` value with a valid route map.',
+  },
+  routeMapLoaderInvalidJson: {
+    code: 'RMX_ROUTE_MAP_LOADER_INVALID_JSON',
+    title: 'Route-map loader returned invalid JSON',
+    fix: 'Check app/routes.ts and make sure route-map loading does not write extra output.',
+  },
+  routeMapLoaderSignal: {
+    code: 'RMX_ROUTE_MAP_LOADER_SIGNAL',
+    title: 'Route-map loader exited from a signal',
+    fix: 'Check app/routes.ts for side effects or runtime issues and try again.',
+  },
+  routeOwnerPlanUnresolved: {
+    code: 'RMX_ROUTE_OWNER_PLAN_UNRESOLVED',
+    title: 'Could not resolve a route owner plan',
+  },
+  routesFileNotFound: {
+    code: 'RMX_ROUTES_FILE_NOT_FOUND',
+    title: 'Could not find app/routes.ts',
+    fix: 'Run this command inside a Remix app that has app/routes.ts.',
+  },
+  targetDirectoryNotEmpty: {
+    code: 'RMX_TARGET_DIRECTORY_NOT_EMPTY',
+    title: 'Target directory is not empty',
+    fix: 'Re-run with --force to continue.',
+  },
+  targetPathNotDirectory: {
+    code: 'RMX_TARGET_PATH_NOT_DIRECTORY',
+    title: 'Target path is not a directory',
+    fix: 'Choose a directory path for the new app target.',
+  },
+  unexpectedExtraArgument: {
+    code: 'RMX_UNEXPECTED_ARGUMENT',
+    title: 'Unexpected extra argument',
+    fix: 'Remove the extra argument or run the command with --help.',
+  },
+  unknownArgument: {
+    code: 'RMX_UNKNOWN_ARGUMENT',
+    title: 'Unknown argument',
+    fix: 'Run the command with --help to see supported arguments.',
+  },
+  unknownCommand: {
+    code: 'RMX_UNKNOWN_COMMAND',
+    title: 'Unknown command',
+    fix: 'Run `remix help` to see available commands.',
+  },
+  unknownCompletionShell: {
+    code: 'RMX_UNKNOWN_COMPLETION_SHELL',
+    title: 'Unknown completion shell',
+    fix: 'Run `remix completion bash` or `remix completion zsh`.',
+  },
+  unknownHelpTopic: {
+    code: 'RMX_UNKNOWN_HELP_TOPIC',
+    title: 'Unknown help topic',
+    fix: 'Run `remix help` to see available commands and help topics.',
+  },
+} satisfies Record<string, CliErrorDefinition>
+
+export class CliError extends Error {
+  code: string
+  context?: CliErrorContext
+  docsUrl?: string
+  fix?: string
+  showHelp: boolean
+  title: string
+
+  constructor(options: CliErrorOptions) {
+    super(options.message)
+    this.code = options.code
+    this.context = options.context
+    this.docsUrl = options.docsUrl
+    this.fix = options.fix
+    this.name = 'CliError'
+    this.showHelp = options.showHelp ?? false
+    this.title = options.title
+  }
+}
+
+export class UsageError extends CliError {
+  constructor(options: CliErrorOptions) {
+    super({ ...options, showHelp: options.showHelp ?? true })
+    this.name = 'UsageError'
+  }
+}
+
+export function appNameUnavailable(targetDir?: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.appNameUnavailable, {
+    context: targetDir == null ? undefined : { targetDir },
+    message: 'Could not determine an app name from the target directory.',
+  })
+}
+
+export function remixVersionUnavailable(): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.remixVersionUnavailable, {
+    message: 'Could not determine the current Remix version.',
+  })
+}
+
+export function invalidCompletionRequest(): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.invalidCompletionRequest, {
+    message: 'Invalid completion request.',
+  })
+}
+
+export function fetchUnavailable(): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.fetchUnavailable, {
+    message: 'This runtime does not provide fetch().',
+  })
+}
+
+export function invalidFlagCombination(details: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.invalidFlagCombination, {
+    context: { details },
+    message: details,
+  })
+}
+
+export function invalidPackageName(input: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.invalidPackageName, {
+    context: { input },
+    message: `Could not derive a valid package name from "${input}".`,
+  })
+}
+
+export function missingOptionValue(option: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.missingOptionValue, {
+    context: { option },
+    message: `${option} requires a value.`,
+  })
+}
+
+export function missingTargetDirectory(): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.missingTargetDirectory, {
+    message: 'A target directory is required.',
+  })
+}
+
+export function projectRootNotFound(startDir?: string): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.projectRootNotFound, {
+    context: startDir == null ? undefined : { startDir },
+    message: 'Could not find a project root. Run this command inside a Remix project.',
+  })
+}
+
+export function remoteSkillDataMissing(name: string): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.remoteSkillDataMissing, {
+    context: { name },
+    message: `Could not find remote data for Remix skill: ${name}`,
+  })
+}
+
+export function routeMapLoaderFailed(details: string): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.routeMapLoaderFailed, {
+    context: { details },
+    message: details,
+  })
+}
+
+export function routeMapLoaderInvalidJson(): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.routeMapLoaderInvalidJson, {
+    message: 'Route-map loader returned invalid JSON.',
+  })
+}
+
+export function routeMapLoaderSignal(signal: NodeJS.Signals): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.routeMapLoaderSignal, {
+    context: { signal },
+    message: `Route-map loader exited from signal ${signal}.`,
+  })
+}
+
+export function routeOwnerPlanUnresolved(routeName: string): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.routeOwnerPlanUnresolved, {
+    context: { routeName },
+    message: `Could not resolve owner plan for "${routeName}".`,
+  })
+}
+
+export function routesFileNotFound(startDir?: string): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.routesFileNotFound, {
+    context: startDir == null ? undefined : { startDir },
+    message: 'Could not find app/routes.ts. Run this command inside a Remix app.',
+  })
+}
+
+export function targetDirectoryNotEmpty(targetDir: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.targetDirectoryNotEmpty, {
+    context: { targetDir },
+    message: `Target directory is not empty: ${targetDir}. Re-run with --force to continue.`,
+  })
+}
+
+export function targetPathNotDirectory(targetDir: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.targetPathNotDirectory, {
+    context: { targetDir },
+    message: `Target path is not a directory: ${targetDir}`,
+  })
+}
+
+export function toCliError(error: unknown): CliError {
+  if (error instanceof CliError) {
+    return error
+  }
+
+  if (error instanceof Error) {
+    return createCliError(CLI_ERROR_DEFINITIONS.internalError, { message: error.message })
+  }
+
+  return createCliError(CLI_ERROR_DEFINITIONS.internalError, { message: String(error) })
+}
+
+export function unknownArgument(argument: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.unknownArgument, {
+    context: { argument },
+    message: `Unknown argument: ${argument}`,
+  })
+}
+
+export function unknownCommand(command: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.unknownCommand, {
+    context: { command },
+    message: `Unknown command: ${command}`,
+  })
+}
+
+export function unknownCompletionShell(shell: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.unknownCompletionShell, {
+    context: { shell },
+    message: `Unknown completion shell: ${shell}`,
+  })
+}
+
+export function unknownHelpTopic(topic: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.unknownHelpTopic, {
+    context: { topic },
+    message: `Unknown help topic: ${topic}`,
+  })
+}
+
+export function unexpectedExtraArgument(argument: string): UsageError {
+  return createUsageError(CLI_ERROR_DEFINITIONS.unexpectedExtraArgument, {
+    context: { argument },
+    message: `Unexpected extra argument: ${argument}`,
+  })
+}
+
+export function renderCliError(error: unknown, options: { helpText?: string } = {}): string {
+  let cliError = toCliError(error)
+  let lines = [`Error [${cliError.code}] ${cliError.title}`, cliError.message]
+
+  if (cliError.fix != null && cliError.fix.length > 0) {
+    lines.push('', 'Try:', `  ${cliError.fix}`)
+  }
+
+  if (cliError.docsUrl != null && cliError.docsUrl.length > 0) {
+    lines.push('', 'Documentation:', `  ${cliError.docsUrl}`)
+  }
+
+  let output = `${lines.join('\n')}\n`
+
+  if (cliError.showHelp && options.helpText != null) {
+    output += `\n${options.helpText}`
+  }
+
+  return output
+}
+
+function createCliError(definition: CliErrorDefinition, options: CreateErrorOptions): CliError {
+  return new CliError({
+    code: definition.code,
+    context: options.context,
+    docsUrl: definition.docsUrl,
+    fix: definition.fix,
+    message: options.message,
+    title: definition.title,
+  })
+}
+
+function createUsageError(definition: CliErrorDefinition, options: CreateErrorOptions): UsageError {
+  return new UsageError({
+    code: definition.code,
+    context: options.context,
+    docsUrl: definition.docsUrl,
+    fix: definition.fix,
+    message: options.message,
+    title: definition.title,
+  })
+}

package/src/lib/help-text.ts

@@ -0,0 +1,88 @@
+import * as process from 'node:process'
+
+import { boldLightBlue, lightYellow } from './terminal.ts'
+
+export interface HelpTextSectionRow {
+  description: string
+  label: string
+}
+
+export interface HelpTextOptions {
+  commands?: HelpTextSectionRow[]
+  description?: string
+  examples?: string[]
+  options?: HelpTextSectionRow[]
+  usage: string[]
+}
+
+const SECTION_INDENT = '  '
+const ROW_GAP = 2
+
+export function formatHelpText(
+  options: HelpTextOptions,
+  target: NodeJS.WriteStream = process.stdout,
+): string {
+  let sections: string[] = [renderUsageSection(options.usage, target)]
+
+  if (options.description != null && options.description.length > 0) {
+    sections.push(options.description)
+  }
+
+  if (options.commands != null && options.commands.length > 0) {
+    sections.push(renderRowSection('Commands', options.commands, target))
+  }
+
+  if (options.options != null && options.options.length > 0) {
+    sections.push(renderRowSection('Options', options.options, target))
+  }
+
+  if (options.examples != null && options.examples.length > 0) {
+    sections.push(renderExamplesSection(options.examples, target))
+  }
+
+  return `${sections.join('\n\n')}\n`
+}
+
+function renderUsageSection(usage: string[], target: NodeJS.WriteStream): string {
+  return renderSection(
+    'Usage',
+    usage.map((line) => `${SECTION_INDENT}${highlightSyntax(line, target)}`),
+    target,
+  )
+}
+
+function renderExamplesSection(examples: string[], target: NodeJS.WriteStream): string {
+  return renderSection(
+    'Examples',
+    examples.map((line) => `${SECTION_INDENT}${highlightSyntax(line, target)}`),
+    target,
+  )
+}
+
+function renderRowSection(
+  title: string,
+  rows: HelpTextSectionRow[],
+  target: NodeJS.WriteStream,
+): string {
+  let labelWidth = rows.reduce((width, row) => Math.max(width, row.label.length), 0) + ROW_GAP
+  let lines = rows.map((row) => {
+    let paddedLabel = row.label.padEnd(labelWidth)
+    return `${SECTION_INDENT}${highlightSyntax(paddedLabel, target)}${row.description}`
+  })
+
+  return renderSection(title, lines, target)
+}
+
+function renderSection(title: string, lines: string[], target: NodeJS.WriteStream): string {
+  return `${formatHeading(title, target)}:\n${lines.join('\n')}`
+}
+
+function formatHeading(title: string, target: NodeJS.WriteStream): string {
+  return boldLightBlue(title, target)
+}
+
+function highlightSyntax(text: string, target: NodeJS.WriteStream): string {
+  return text.replace(/(--[A-Za-z0-9-]+|-[A-Za-z]|\[[A-Za-z][A-Za-z0-9-]*\]|<[^>\n]+>)/g, (token) =>
+    lightYellow(token, target),
+  )
+}

package/src/lib/load-route-map-worker.ts

@@ -0,0 +1,110 @@
+import * as process from 'node:process'
+import { pathToFileURL } from 'node:url'
+
+import type { RawRouteTreeNode } from './route-map.ts'
+
+void run().catch((error: unknown) => {
+  if (error instanceof Error) {
+    process.stderr.write(`${error.message}\n`)
+  } else {
+    process.stderr.write(`${String(error)}\n`)
+  }
+
+  setExitCode(1)
+})
+
+async function run(): Promise<void> {
+  let routesFile = process.argv[2]
+  if (typeof routesFile !== 'string' || routesFile.length === 0) {
+    throw new Error('Missing app/routes.ts path.')
+  }
+
+  let tree = await loadRawRouteTree(routesFile)
+  process.stdout.write(JSON.stringify(tree))
+}
+
+async function loadRawRouteTree(routesFile: string): Promise<RawRouteTreeNode[]> {
+  let routeModule = await import(pathToFileURL(routesFile).href)
+
+  if (!('routes' in routeModule)) {
+    throw new Error(`Route module ${routesFile} must export a named "routes" value.`)
+  }
+
+  return normalizeRouteGroup(Reflect.get(routeModule, 'routes'), [], new Map())
+}
+
+function normalizeRouteGroup(
+  value: unknown,
+  parentSegments: string[],
+  seen: Map<object, string>,
+): RawRouteTreeNode[] {
+  if (!isPlainObject(value)) {
+    let location = parentSegments.length === 0 ? 'routes' : parentSegments.join('.')
+    throw new Error(`Invalid route map value at "${location}". Expected a nested route object.`)
+  }
+
+  let existingPath = seen.get(value)
+  let currentPath = parentSegments.length === 0 ? 'routes' : parentSegments.join('.')
+  if (existingPath != null) {
+    throw new Error(`Detected a route map cycle at "${currentPath}" via "${existingPath}".`)
+  }
+
+  seen.set(value, currentPath)
+
+  try {
+    return Object.entries(value).map(([key, entryValue]) => {
+      let nameSegments = [...parentSegments, key]
+      let name = nameSegments.join('.')
+
+      if (isRouteLeaf(entryValue)) {
+        return {
+          children: [],
+          key,
+          kind: 'route',
+          method: entryValue.method,
+          name,
+          pattern: entryValue.pattern.source,
+        } satisfies RawRouteTreeNode
+      }
+
+      if (isPlainObject(entryValue)) {
+        return {
+          children: normalizeRouteGroup(entryValue, nameSegments, seen),
+          key,
+          kind: 'group',
+          name,
+        } satisfies RawRouteTreeNode
+      }
+
+      throw new Error(
+        `Invalid route map value at "${name}". Expected a route or nested route object.`,
+      )
+    })
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function isRouteLeaf(value: unknown): value is { method: string; pattern: { source: string } } {
+  return (
+    typeof value === 'object' &&
+    value != null &&
+    typeof Reflect.get(value, 'method') === 'string' &&
+    typeof Reflect.get(value, 'pattern') === 'object' &&
+    Reflect.get(value, 'pattern') != null &&
+    typeof Reflect.get(Reflect.get(value, 'pattern'), 'source') === 'string'
+  )
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value == null) {
+    return false
+  }
+
+  let prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function setExitCode(exitCode: number) {
+  globalThis.process.exitCode = exitCode
+}

package/src/lib/parse-args.ts

@@ -0,0 +1,82 @@
+import { missingOptionValue, unexpectedExtraArgument, unknownArgument } from './errors.ts'
+
+export interface ParseArgsBooleanOptionSpec {
+  flag: string
+  type: 'boolean'
+}
+
+export interface ParseArgsStringOptionSpec {
+  flag: string
+  type: 'string'
+}
+
+export type ParseArgsOptionSpec = ParseArgsBooleanOptionSpec | ParseArgsStringOptionSpec
+
+export type ParseArgsOptionDefinitions = Record<string, ParseArgsOptionSpec>
+
+export interface ParseArgsOptions {
+  maxPositionals?: number
+}
+
+export type ParsedArgsValues<definitions extends ParseArgsOptionDefinitions> = {
+  [key in keyof definitions]: definitions[key]['type'] extends 'boolean'
+    ? boolean
+    : string | undefined
+}
+
+export interface ParsedArgsResult<definitions extends ParseArgsOptionDefinitions> {
+  options: ParsedArgsValues<definitions>
+  positionals: string[]
+}
+
+export function parseArgs<const definitions extends ParseArgsOptionDefinitions>(
+  argv: string[],
+  definitions: definitions,
+  options: ParseArgsOptions = {},
+): ParsedArgsResult<definitions> {
+  let values = {} as ParsedArgsValues<definitions>
+  let specsByFlag = new Map<string, { key: keyof definitions; spec: ParseArgsOptionSpec }>()
+  let positionals: string[] = []
+
+  for (let [key, spec] of Object.entries(definitions) as Array<
+    [keyof definitions, ParseArgsOptionSpec]
+  >) {
+    values[key] = (
+      spec.type === 'boolean' ? false : undefined
+    ) as ParsedArgsValues<definitions>[typeof key]
+    specsByFlag.set(spec.flag, { key, spec })
+  }
+
+  for (let index = 0; index < argv.length; index++) {
+    let arg = argv[index]!
+    let resolved = specsByFlag.get(arg)
+
+    if (resolved != null) {
+      if (resolved.spec.type === 'boolean') {
+        values[resolved.key] = true as ParsedArgsValues<definitions>[typeof resolved.key]
+        continue
+      }
+
+      let next = argv[index + 1]
+      if (next == null || next.startsWith('-')) {
+        throw missingOptionValue(arg)
+      }
+
+      values[resolved.key] = next as ParsedArgsValues<definitions>[typeof resolved.key]
+      index += 1
+      continue
+    }
+
+    if (arg.startsWith('-')) {
+      throw unknownArgument(arg)
+    }
+
+    if (options.maxPositionals != null && positionals.length >= options.maxPositionals) {
+      throw unexpectedExtraArgument(arg)
+    }
+
+    positionals.push(arg)
+  }
+
+  return { options: values, positionals }
+}