@remix-run/cli 0.0.0 → 0.1.0

package/src/lib/commands/routes.ts

@@ -0,0 +1,251 @@
+import * as process from 'node:process'
+
+import type { CliContext } from '../cli-context.ts'
+import { invalidFlagCombination, renderCliError, toCliError } from '../errors.ts'
+import { formatHelpText } from '../help-text.ts'
+import { parseArgs } from '../parse-args.ts'
+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/'
+
+export async function runRoutesCommand(argv: string[], context: CliContext): Promise<number> {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(getRoutesCommandHelpText())
+    return 0
+  }
+
+  try {
+    let options = parseRoutesCommandArgs(argv)
+    let routeMap = await loadRouteMap(context.cwd)
+
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(routeMap, null, 2)}\n`)
+    } else {
+      let reporter = createCommandReporter({ remixVersion: context.remixVersion })
+      writeRouteMap(reporter.out, routeMap, options)
+      reporter.finish()
+    }
+
+    return 0
+  } catch (error) {
+    process.stderr.write(
+      renderCliError(toCliError(error), { helpText: getRoutesCommandHelpText(process.stderr) }),
+    )
+    return 1
+  }
+}
+
+export function getRoutesCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return formatHelpText(
+    {
+      description: 'Show the Remix route tree for the current app.',
+      examples: [
+        'remix routes',
+        'remix routes --table',
+        'remix routes --table --no-headers',
+        'remix routes --verbose',
+        'remix routes --json',
+      ],
+      options: [
+        { description: 'Print the normalized route tree as JSON', label: '--json' },
+        { description: 'Print routes as a flat table', label: '--table' },
+        {
+          description: 'Omit the table header row when using --table',
+          label: '--no-headers',
+        },
+        { description: 'Show full owner paths in tree or table output', label: '--verbose' },
+      ],
+      usage: ['remix routes [--json | --table] [--no-headers] [--verbose] [--no-color]'],
+    },
+    target,
+  )
+}
+
+interface RoutesCommandOptions {
+  json: boolean
+  noHeaders: boolean
+  table: boolean
+  verbose: boolean
+}
+
+function parseRoutesCommandArgs(argv: string[]): RoutesCommandOptions {
+  let parsed = parseArgs(
+    argv,
+    {
+      json: { flag: '--json', type: 'boolean' },
+      noHeaders: { flag: '--no-headers', type: 'boolean' },
+      table: { flag: '--table', type: 'boolean' },
+      verbose: { flag: '--verbose', type: 'boolean' },
+    },
+    { maxPositionals: 0 },
+  )
+
+  let json = parsed.options.json
+  let noHeaders = parsed.options.noHeaders
+  let table = parsed.options.table
+  let verbose = parsed.options.verbose
+
+  if (json && table) {
+    throw invalidFlagCombination('Cannot combine --json with --table.')
+  }
+
+  if (json && verbose) {
+    throw invalidFlagCombination('Cannot combine --json with --verbose.')
+  }
+
+  if (noHeaders && !table) {
+    throw invalidFlagCombination('Cannot use --no-headers without --table.')
+  }
+
+  return { json, noHeaders, table, verbose }
+}
+
+function writeRouteMap(
+  out: TextChannel,
+  routeMap: LoadedRouteMap,
+  options: RoutesCommandOptions,
+): void {
+  if (routeMap.tree.length === 0) {
+    out.line('No routes.')
+    return
+  }
+
+  if (options.table) {
+    writeRouteTable(out, routeMap, options)
+    return
+  }
+
+  let lines: string[] = []
+  renderRouteNodes(lines, routeMap.tree, '', true, null, options)
+  for (let line of lines) {
+    out.line(line)
+  }
+}
+
+function renderRouteNodes(
+  lines: string[],
+  nodes: RouteTreeNode[],
+  prefix: string,
+  isRoot: boolean,
+  parentOwnerPath: string | null,
+  options: RoutesCommandOptions,
+): void {
+  let leafKeyWidth = getLeafKeyWidth(nodes)
+
+  nodes.forEach((node, index) => {
+    renderRouteNode(
+      lines,
+      node,
+      prefix,
+      index === nodes.length - 1,
+      isRoot,
+      parentOwnerPath,
+      leafKeyWidth,
+      options,
+    )
+  })
+}
+
+function renderRouteNode(
+  lines: string[],
+  node: RouteTreeNode,
+  prefix: string,
+  isLast: boolean,
+  isRoot: boolean,
+  parentOwnerPath: string | null,
+  leafKeyWidth: number,
+  options: RoutesCommandOptions,
+): void {
+  let branch = isRoot ? '' : isLast ? '└─ ' : '├─ '
+  let line = `${prefix}${branch}${formatRouteNode(node, parentOwnerPath, leafKeyWidth, options)}`
+  lines.push(colorRouteLine(line, node))
+
+  if (node.kind !== 'group') {
+    return
+  }
+
+  let childPrefix = isRoot ? '' : `${prefix}${isLast ? '   ' : '│  '}`
+  renderRouteNodes(lines, node.children, childPrefix, false, node.owner.path, options)
+}
+
+function getLeafKeyWidth(nodes: RouteTreeNode[]): number {
+  let leafNodes = nodes.filter((node) => node.kind === 'route')
+
+  return leafNodes.reduce((width, node) => Math.max(width, node.key.length), 0)
+}
+
+function formatRouteNode(
+  node: RouteTreeNode,
+  parentOwnerPath: string | null,
+  leafKeyWidth: number,
+  options: RoutesCommandOptions,
+): string {
+  let owner = formatOwner(node, options)
+
+  if (node.kind === 'group') {
+    return `${node.key} -> ${owner}`
+  }
+
+  let leaf = `${node.key.padEnd(leafKeyWidth)}  ${node.method!.padEnd(6)} ${node.pattern}`
+
+  if (options.verbose || parentOwnerPath == null || parentOwnerPath !== node.owner.path) {
+    return `${leaf} -> ${owner}`
+  }
+
+  return leaf
+}
+
+function writeRouteTable(
+  out: TextChannel,
+  routeMap: LoadedRouteMap,
+  options: RoutesCommandOptions,
+): void {
+  let rows = flattenRoutes(routeMap.tree).map((node) => ({
+    method: node.method!,
+    node,
+    owner: formatOwner(node, options),
+    path: node.pattern!,
+    route: node.name,
+  }))
+  out.table({
+    formatRow(line, rowIndex) {
+      return colorRouteLine(line, rows[rowIndex]!.node)
+    },
+    headers: ['Route', 'Method', 'Path', 'Owner'],
+    noHeaders: options.noHeaders,
+    rows: rows.map((row) => [row.route, row.method, row.path, row.owner]),
+  })
+}
+
+function flattenRoutes(nodes: RouteTreeNode[], routes: RouteTreeNode[] = []): RouteTreeNode[] {
+  for (let node of nodes) {
+    if (node.kind === 'route') {
+      routes.push(node)
+      continue
+    }
+
+    flattenRoutes(node.children, routes)
+  }
+
+  return routes
+}
+
+function formatOwner(node: RouteTreeNode, options: RoutesCommandOptions): string {
+  let ownerPath = options.verbose ? node.owner.path : getCompactOwnerPath(node.owner.path)
+
+  return `${ownerPath}${node.owner.exists ? '' : ' [missing]'}`
+}
+
+function colorRouteLine(line: string, node: RouteTreeNode): string {
+  return node.owner.exists ? line : lightRed(line)
+}
+
+function getCompactOwnerPath(ownerPath: string): string {
+  if (ownerPath.startsWith(CONTROLLERS_PATH_PREFIX)) {
+    return ownerPath.slice(CONTROLLERS_PATH_PREFIX.length)
+  }
+
+  return ownerPath
+}

package/src/lib/commands/skills.ts

@@ -0,0 +1,306 @@
+import * as process from 'node:process'
+
+import type { CliContext } from '../cli-context.ts'
+import { getDisplayPath } from '../display-path.ts'
+import { renderCliError, toCliError, unknownSkillsCommand } from '../errors.ts'
+import { formatHelpText } from '../help-text.ts'
+import { parseArgs } from '../parse-args.ts'
+import type { SkillChange, SkillsInstallPhase, SkillsProgressReporter } from '../skills.ts'
+import { getSkillsOverview, installRemixSkills } from '../skills.ts'
+import {
+  createCommandReporter,
+  createStepProgressReporter,
+  type CommandReporter,
+} from '../reporter.ts'
+
+const SKILLS_PROGRESS_LABELS = {
+  'compare-local-skills': 'Compare local skills',
+  'download-remix-skills-archive': 'Download Remix skills archive',
+  'fetch-remix-skills-metadata': 'Fetch Remix skills metadata from GitHub',
+  'read-local-skills-cache': 'Read local skills cache',
+  'resolve-project-root': 'Resolve project root',
+  'write-updated-skills': 'Write updated skills',
+} satisfies Record<SkillsInstallPhase, string>
+
+export async function runSkillsCommand(argv: string[], context: CliContext): Promise<number> {
+  if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+    process.stdout.write(getSkillsCommandHelpText())
+    return 0
+  }
+
+  let [subcommand, ...rest] = argv
+
+  try {
+    if (subcommand === 'install') {
+      return await runSkillsInstallCommand(rest, context)
+    }
+
+    if (subcommand === 'list') {
+      return await runSkillsListCommand(rest, context)
+    }
+
+    throw unknownSkillsCommand(subcommand)
+  } catch (error) {
+    process.stderr.write(
+      renderCliError(toCliError(error), { helpText: getSkillsCommandHelpText(process.stderr) }),
+    )
+    return 1
+  }
+}
+
+export function getSkillsCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return formatHelpText(
+    {
+      commands: [
+        {
+          description: 'Install Remix skills into a local directory',
+          label: 'install [--dir <path>]',
+        },
+        {
+          description: 'List Remix skills and local status',
+          label: 'list [--dir <path>] [--json]',
+        },
+      ],
+      description: 'Manage Remix skills for the current project.',
+      examples: [
+        'remix skills install',
+        'remix skills install --dir custom/skills',
+        'remix skills list --dir custom/skills',
+        'remix skills list --json',
+      ],
+      usage: ['remix skills <command>'],
+    },
+    target,
+  )
+}
+
+export function getSkillsInstallCommandHelpText(
+  target: NodeJS.WriteStream = process.stdout,
+): string {
+  return formatHelpText(
+    {
+      description: 'Install or refresh Remix skills in .agents/skills for the current project.',
+      examples: ['remix skills install', 'remix skills install --dir custom/skills'],
+      options: [
+        {
+          description: 'Install skills into a custom directory relative to the project root',
+          label: '--dir <path>',
+        },
+      ],
+      usage: ['remix skills install [--dir <path>]'],
+    },
+    target,
+  )
+}
+
+export function getSkillsListCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return formatHelpText(
+    {
+      description:
+        'List Remix skills and show whether each one is installed, outdated, or missing locally.',
+      examples: [
+        'remix skills list',
+        'remix skills list --dir custom/skills',
+        'remix skills list --json',
+      ],
+      options: [
+        {
+          description: 'Read local skills from a custom directory relative to the project root',
+          label: '--dir <path>',
+        },
+        { description: 'Print skill state as JSON', label: '--json' },
+      ],
+      usage: ['remix skills list [--dir <path>] [--json]'],
+    },
+    target,
+  )
+}
+
+async function runSkillsInstallCommand(argv: string[], context: CliContext): Promise<number> {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(getSkillsInstallCommandHelpText())
+    return 0
+  }
+
+  let reporter: CommandReporter | null = null
+  let progress: SkillsProgressReporter | null = null
+
+  try {
+    let options = parseSkillsInstallCommandArgs(argv)
+    reporter = createCommandReporter({ remixVersion: context.remixVersion })
+    progress = createSkillsProgressReporter(reporter)
+    let cwd = context.cwd
+
+    await reporter.status.commandHeader('skills install')
+    let result = await installRemixSkills(cwd, globalThis.fetch, {
+      progress,
+      skillsDir: options.dir ?? undefined,
+    })
+    let skillsDir = getDisplayPath(result.skillsDir, cwd)
+    progress.writeSummaryGap()
+    if (result.appliedChanges.length === 0) {
+      reporter.out.line(`No changes. ${skillsDir} is up to date.`)
+      reporter.finish()
+      return 0
+    }
+
+    reporter.out.line(`Synced Remix skills into ${skillsDir}:`)
+    reporter.out.bullets(formatAppliedChanges(result.appliedChanges))
+    reporter.finish()
+    return 0
+  } catch (error) {
+    progress?.writeSummaryGap()
+    process.stderr.write(
+      renderCliError(toCliError(error), {
+        helpText: getSkillsInstallCommandHelpText(process.stderr),
+      }),
+    )
+    reporter?.finish()
+    return 1
+  }
+}
+
+async function runSkillsListCommand(argv: string[], context: CliContext): Promise<number> {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(getSkillsListCommandHelpText())
+    return 0
+  }
+
+  let reporter: CommandReporter | null = null
+  let progress: SkillsProgressReporter | null = null
+
+  try {
+    let options = parseSkillsDirArgs(argv, { allowJson: true })
+    let cwd = context.cwd
+    reporter = options.json ? null : createCommandReporter({ remixVersion: context.remixVersion })
+    if (reporter != null) {
+      progress = createSkillsProgressReporter(reporter)
+      await reporter.status.commandHeader('skills list')
+    }
+
+    let result = await getSkillsOverview(cwd, globalThis.fetch, {
+      progress: progress ?? undefined,
+      skillsDir: options.dir ?? undefined,
+    })
+
+    if (options.json) {
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            entries: result.entries,
+            projectRoot: result.projectRoot,
+            skillsDir: result.skillsDir,
+          },
+          null,
+          2,
+        )}\n`,
+      )
+      return 0
+    }
+
+    progress?.writeSummaryGap()
+    if (reporter == null) {
+      return 0
+    }
+
+    let listReporter = reporter
+    listReporter.out.line(
+      formatSkillsListSummary(result.entries, getDisplayPath(result.skillsDir, cwd)),
+    )
+    listReporter.out.bullets(
+      result.entries.map((entry) => formatSkillListEntry(listReporter, entry)),
+    )
+    listReporter.finish()
+    return 0
+  } catch (error) {
+    progress?.writeSummaryGap()
+    process.stderr.write(
+      renderCliError(toCliError(error), { helpText: getSkillsListCommandHelpText(process.stderr) }),
+    )
+    reporter?.finish()
+    return 1
+  }
+}
+
+function createSkillsProgressReporter(reporter: CommandReporter): SkillsProgressReporter {
+  return createStepProgressReporter(reporter.status, SKILLS_PROGRESS_LABELS)
+}
+
+function formatAppliedChanges(changes: SkillChange[]): string[] {
+  let showAction = changes.some((change) => change.action !== 'add')
+  return changes.map((change) =>
+    showAction ? `${toPastTense(change.action)} ${change.name}` : change.name,
+  )
+}
+
+function formatSkillListEntry(
+  reporter: CommandReporter,
+  entry: { name: string; state: 'installed' | 'missing' | 'outdated' },
+): string {
+  if (entry.state === 'installed') {
+    return entry.name
+  }
+
+  let tone: 'error' | 'warn' = entry.state === 'missing' ? 'error' : 'warn'
+  return `${entry.name} ${reporter.out.label(entry.state, '', { tone })}`
+}
+
+function formatSkillsListSummary(
+  entries: Array<{ name: string; state: 'installed' | 'missing' | 'outdated' }>,
+  skillsDir: string,
+): string {
+  let installedCount = entries.filter((entry) => entry.state === 'installed').length
+  let outdatedCount = entries.filter((entry) => entry.state === 'outdated').length
+  let missingCount = entries.filter((entry) => entry.state === 'missing').length
+  let detailParts = [
+    installedCount > 0 ? `${installedCount} installed` : null,
+    outdatedCount > 0 ? `${outdatedCount} outdated` : null,
+    missingCount > 0 ? `${missingCount} missing` : null,
+  ].filter((part) => part != null)
+
+  let detail = detailParts.length === 0 ? '0 installed' : detailParts.join(', ')
+  return `Checked Remix skills against ${skillsDir}: ${detail}.`
+}
+
+function parseSkillsInstallCommandArgs(argv: string[]): { dir: string | null } {
+  let { dir } = parseSkillsDirArgs(argv)
+  return { dir }
+}
+
+function parseSkillsDirArgs(
+  argv: string[],
+  options: { allowJson?: boolean } = {},
+): { dir: string | null; json: boolean } {
+  if (options.allowJson) {
+    let parsed = parseArgs(
+      argv,
+      {
+        dir: { flag: '--dir', type: 'string' },
+        json: { flag: '--json', type: 'boolean' },
+      },
+      { maxPositionals: 0 },
+    )
+
+    return {
+      dir: parsed.options.dir ?? null,
+      json: parsed.options.json,
+    }
+  }
+
+  let parsed = parseArgs(
+    argv,
+    {
+      dir: { flag: '--dir', type: 'string' },
+    },
+    { maxPositionals: 0 },
+  )
+
+  return {
+    dir: parsed.options.dir ?? null,
+    json: false,
+  }
+}
+
+function toPastTense(action: 'add' | 'replace'): string {
+  return action === 'add' ? 'added' : 'replaced'
+}

package/src/lib/commands/test.ts

@@ -0,0 +1,25 @@
+import { getRemixTestHelpText, runRemixTest } from '@remix-run/test/cli'
+import * as process from 'node:process'
+
+import type { CliContext } from '../cli-context.ts'
+import { renderCliError, toCliError } from '../errors.ts'
+
+export async function runTestCommand(argv: string[], context: CliContext): Promise<number> {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(`${getTestCommandHelpText()}\n`)
+    return 0
+  }
+
+  try {
+    return await runRemixTest({ argv, cwd: context.cwd })
+  } catch (error) {
+    process.stderr.write(
+      renderCliError(toCliError(error), { helpText: getTestCommandHelpText(process.stderr) }),
+    )
+    return 1
+  }
+}
+
+export function getTestCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return getRemixTestHelpText(target)
+}

package/src/lib/commands/version.ts

@@ -0,0 +1,39 @@
+import * as process from 'node:process'
+
+import type { CliContext } from '../cli-context.ts'
+import { remixVersionUnavailable, renderCliError, toCliError } from '../errors.ts'
+import { formatHelpText } from '../help-text.ts'
+import { parseArgs } from '../parse-args.ts'
+
+export async function runVersionCommand(argv: string[], context: CliContext): Promise<number> {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(getVersionCommandHelpText())
+    return 0
+  }
+
+  try {
+    parseArgs(argv, {}, { maxPositionals: 0 })
+    if (context.remixVersion == null) {
+      throw remixVersionUnavailable()
+    }
+
+    process.stdout.write(`${context.remixVersion}\n`)
+    return 0
+  } catch (error) {
+    process.stderr.write(
+      renderCliError(toCliError(error), { helpText: getVersionCommandHelpText(process.stderr) }),
+    )
+    return 1
+  }
+}
+
+export function getVersionCommandHelpText(target: NodeJS.WriteStream = process.stdout): string {
+  return formatHelpText(
+    {
+      description: 'Show the current Remix version.',
+      examples: ['remix version', 'remix --version'],
+      usage: ['remix version'],
+    },
+    target,
+  )
+}