@c9up/ream 0.2.25 → 0.2.27

package/src/dev/readyBanner.ts

@@ -0,0 +1,84 @@
+/**
+ * What the dev server says once it is listening.
+ *
+ * Upstream prints a sticker the moment the child reports ready: the address,
+ * the mode, how long the boot took. Read off `@adonisjs/assembler`'s build:
+ *
+ *     this.ui.sticker()
+ *       .add(`Server address: ${colors.cyan(serverUrl)}`)
+ *       .add(`Mode: ${colors.cyan(this.mode)}`)
+ *       .add(`Ready in: ${colors.cyan(prettyHrtime(message.duration))}`)
+ *
+ * Ours says the same, `Press h to show help` included — the shortcuts are in
+ * `./shortcuts.ts`, so the line is an offer this process keeps.
+ *
+ * Printed from the application rather than from the `ream dev` parent, which
+ * is where upstream prints it. The parent is a Rust process here and the port
+ * is not its to know: a dev server that found 3000 taken binds 3001, and only
+ * the process that bound it can say so. Upstream solves the same problem by
+ * having the child send the port over IPC — the address it prints is the
+ * child's either way.
+ */
+
+import { lumen } from '@c9up/lumen'
+
+/** Whether `ream dev` is what started this process. */
+export function inDevServer(): boolean {
+  return process.env.REAM_DEV === 'true'
+}
+
+export interface ReadyBanner {
+  /** The host the server bound, as the Ignitor resolved it. */
+  host: string
+  port: number
+  /** `HMR` when the loader is swapping modules, `watch` when it only restarts. */
+  mode: string
+  /** Milliseconds from process start to listening. */
+  bootMs?: number
+}
+
+/**
+ * The address to show for a bound host and port.
+ *
+ * `localhost` rather than `0.0.0.0`: bound to every interface is not a link
+ * that opens, and printing it sends you looking in the wrong place. Shared
+ * with the `o` shortcut so the browser goes where the sticker said.
+ */
+export function devServerUrl(host: string, port: number): string {
+  const shown = host === '0.0.0.0' || host === '::' ? 'localhost' : host
+  return `http://${shown}:${port}`
+}
+
+/** The lines of the sticker, so a test can read them without a terminal. */
+export function readyBannerLines(banner: ReadyBanner): string[] {
+  const ui = lumen()
+  const lines = [
+    `Server address: ${ui.colors.cyan(devServerUrl(banner.host, banner.port))}`,
+    `Mode: ${ui.colors.cyan(banner.mode)}`,
+  ]
+  if (banner.bootMs !== undefined) {
+    lines.push(`Ready in: ${ui.colors.cyan(formatBootTime(banner.bootMs))}`)
+  }
+  // Only where there is a keyboard: piped into a file, the offer is a lie.
+  if (process.stdin.isTTY) lines.push(`Press ${ui.colors.dim('h')} to show help`)
+  return lines
+}
+
+/** Print it, the way upstream prints its sticker. */
+export function printReadyBanner(banner: ReadyBanner): void {
+  const ui = lumen()
+  const sticker = ui.sticker()
+  for (const line of readyBannerLines(banner)) sticker.add(line)
+  sticker.render()
+}
+
+/**
+ * `412 ms`, `1.2 s` — upstream runs the duration through `pretty-hrtime`.
+ *
+ * Not that dependency: this prints one number once per boot, and the package
+ * is 60 lines of unit selection for a case we have exactly one of.
+ */
+function formatBootTime(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)} ms`
+  return `${(ms / 1000).toFixed(1)} s`
+}

package/src/dev/shortcuts.ts

@@ -0,0 +1,158 @@
+/**
+ * The keys the dev server answers to.
+ *
+ * Upstream's set, read off `@adonisjs/assembler`'s build: `r` restarts, `c`
+ * clears, `o` opens the browser, `h` shows the list, and Ctrl-C or Ctrl-D
+ * quits. Same keys, same order, same words.
+ *
+ * Owned by the application rather than by the `ream dev` parent, which is
+ * where upstream owns it — the same split as the ready sticker, and for the
+ * same reason: `o` needs the address, and a port found by scanning past a
+ * taken 3000 is known only to the process that bound it. Everything else
+ * follows from there, because this process already has what each key needs:
+ * exiting on the restart code is what makes the parent start it again, and
+ * the graceful shutdown is already wired to a signal.
+ *
+ * NO dependency for opening a browser. Upstream imports `open`; this spawns
+ * the platform's opener, which is the one thing that package does on the three
+ * platforms a dev server runs on.
+ */
+
+import { spawn } from 'node:child_process'
+import { lumen } from '@c9up/lumen'
+import { clearScreen } from './fullReload.js'
+
+/** The exit code the `ream dev` parent restarts on. */
+export const RESTART_EXIT_CODE = 75
+
+interface Shortcut {
+  key: string
+  description: string
+  handler: () => void
+}
+
+export interface ShortcutsOptions {
+  /** Where the server is listening, for `o`. */
+  url?: string
+  /** Leave the process the way a restart leaves it. Defaults to exiting. */
+  onRestart?: () => void
+  /** End the session. Defaults to exiting through the normal shutdown. */
+  onQuit?: () => void
+}
+
+/** The lines `h` prints, so a test can read them without a terminal. */
+export function helpLines(): string[] {
+  return ['Available shortcuts:', ...shortcutsFor({}).map((s) => `· ${s.key}: ${s.description}`)]
+}
+
+function shortcutsFor(options: ShortcutsOptions): Shortcut[] {
+  const ui = lumen()
+  return [
+    {
+      key: 'r',
+      description: 'restart server',
+      handler: () => {
+        ui.logger.log('')
+        ui.logger.info('Manual restart triggered...')
+        // Exiting on the restart code IS the restart: the parent loops on it,
+        // which is the same path a change outside the boundaries takes.
+        if (options.onRestart) options.onRestart()
+        else process.exit(RESTART_EXIT_CODE)
+      },
+    },
+    {
+      key: 'c',
+      description: 'clear console',
+      handler: () => {
+        clearScreen()
+        ui.logger.info('Console cleared')
+      },
+    },
+    {
+      key: 'o',
+      description: 'open in browser',
+      handler: () => {
+        if (options.url === undefined) {
+          ui.logger.warning('No server address to open')
+          return
+        }
+        ui.logger.log('')
+        ui.logger.info(`Opening ${options.url}...`)
+        openBrowser(options.url)
+      },
+    },
+    {
+      key: 'h',
+      description: 'show this help',
+      handler: () => {
+        ui.logger.log('')
+        for (const line of helpLines()) ui.logger.log(line)
+      },
+    },
+  ]
+}
+
+/** What to do with one keypress. Exported so the mapping is testable. */
+export function handleKey(key: string, options: ShortcutsOptions = {}): boolean {
+  // \u0003 is Ctrl-C and \u0004 is Ctrl-D. Raw mode means no signal is raised
+  // for either, so the process would sit there unkillable without this.
+  if (key === '\u0003' || key === '\u0004') {
+    if (options.onQuit) options.onQuit()
+    else process.kill(process.pid, 'SIGINT')
+    return true
+  }
+  const shortcut = shortcutsFor(options).find((entry) => entry.key === key)
+  if (shortcut === undefined) return false
+  shortcut.handler()
+  return true
+}
+
+/**
+ * Listen for keys. Answers a function that stops listening.
+ *
+ * A no-op when stdin is not a terminal — `ream dev` piped into a file has no
+ * keyboard, and raw mode on a pipe throws.
+ */
+export function installShortcuts(options: ShortcutsOptions = {}): () => void {
+  if (!process.stdin.isTTY) return () => {}
+
+  const onData = (data: Buffer | string): void => {
+    handleKey(data.toString(), options)
+  }
+  process.stdin.setRawMode(true)
+  process.stdin.on('data', onData)
+  // Nothing should stay alive for a keyboard: a server that finished its work
+  // must be able to exit with a listener still attached.
+  process.stdin.unref()
+
+  return () => {
+    process.stdin.setRawMode(false)
+    process.stdin.removeListener('data', onData)
+    process.stdin.pause()
+  }
+}
+
+/**
+ * Hand the URL to whatever opens links here.
+ *
+ * Detached and ignored: an opener that writes to stderr, or outlives the dev
+ * server, must not take the terminal or the exit with it.
+ */
+function openBrowser(url: string): void {
+  const command =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'
+  try {
+    const child = spawn(command, [url], {
+      detached: true,
+      stdio: 'ignore',
+      shell: process.platform === 'win32',
+    })
+    child.unref()
+    child.on('error', () => {
+      // No opener on this machine — a headless container, say. The address was
+      // printed a moment ago; losing the click is not worth a crash.
+    })
+  } catch {
+    // Same.
+  }
+}

package/src/errors/prettyPrintError.ts

@@ -7,14 +7,14 @@
  */
 
 import { ReamError } from './ReamError.js'
+import { renderError } from './renderError.js'
 
 export function prettyPrintError(error: unknown): void {
+  // A framework error already says what it is, what it was doing and what to
+  // try — printing a source excerpt under it would bury that.
   if (error instanceof ReamError) {
     console.error(error.toDevString())
-  } else if (error instanceof Error) {
-    console.error(`\n  ${error.message}\n`)
-    if (error.stack) console.error(error.stack)
-  } else {
-    console.error(error)
+    return
   }
+  console.error(renderError(error))
 }

package/src/errors/renderError.ts

@@ -0,0 +1,230 @@
+/**
+ * An error, rendered for someone reading a terminal.
+ *
+ * Upstream hands this to youch. Written here instead, for the reason lumen was
+ * written rather than a colour package taken: a dependency is code we do not
+ * control, shipped into every application that installs the framework.
+ *
+ * The expensive part of doing this properly is usually reading source maps to
+ * get from a transpiled frame back to the line someone wrote. It is not needed
+ * here: `ream dev` runs TypeScript through swc-node, which already reports
+ * `app/controllers/users_controller.ts:24:11` — measured, not assumed. A build
+ * that does not, or a frame whose file cannot be read, falls back to the plain
+ * stack rather than showing nothing.
+ *
+ * NOTHING here may throw. This is what runs when something has already gone
+ * wrong, and an error thrown while rendering an error replaces the one you
+ * needed to see.
+ */
+
+import { readFileSync } from 'node:fs'
+import { relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { ansiColors, silentColors, supportsColor } from '@c9up/lumen'
+
+/** One line of a stack, taken apart. */
+export interface StackFrame {
+  /** The function, when the runtime named one. */
+  callee?: string
+  file: string
+  line: number
+  column: number
+  /** Where it comes from, which is what decides how much of it is shown. */
+  origin: 'application' | 'dependency' | 'runtime'
+}
+
+export interface RenderOptions {
+  /** Paths are printed relative to this. Defaults to the working directory. */
+  cwd?: string
+  /** Lines of source shown around the failing one. */
+  context?: number
+  /** Force colour on or off. Defaults to what the stream takes. */
+  colors?: boolean
+}
+
+const AT_WITH_CALLEE = /^\s*at\s+(.+?)\s+\((.+):(\d+):(\d+)\)$/
+const AT_BARE = /^\s*at\s+(.+):(\d+):(\d+)$/
+
+/**
+ * Take a stack apart.
+ *
+ * A line that matches neither shape is dropped rather than guessed at: a
+ * malformed frame in the middle of a trace is worse than a shorter trace.
+ */
+export function parseStack(stack: string | undefined, cwd: string): StackFrame[] {
+  if (stack === undefined) return []
+  const frames: StackFrame[] = []
+
+  for (const raw of stack.split('\n').slice(1)) {
+    const withCallee = AT_WITH_CALLEE.exec(raw)
+    const bare = withCallee === null ? AT_BARE.exec(raw) : null
+    const parts = withCallee ?? bare
+    if (parts === null) continue
+
+    const callee = withCallee === null ? undefined : parts[1]
+    const location = withCallee === null ? parts[1] : parts[2]
+    const line = Number(withCallee === null ? parts[2] : parts[3])
+    const column = Number(withCallee === null ? parts[3] : parts[4])
+    if (location === undefined || !Number.isInteger(line)) continue
+
+    const file = toPath(location)
+    frames.push({
+      ...(callee === undefined ? {} : { callee }),
+      file,
+      line,
+      column: Number.isInteger(column) ? column : 0,
+      origin: originOf(file, cwd),
+    })
+  }
+  return frames
+}
+
+/** The whole thing: message, the failing line in context, the trace, the cause. */
+export function renderError(error: unknown, options: RenderOptions = {}): string {
+  try {
+    return render(error, options, new Set())
+  } catch {
+    // The renderer failed on the error it was asked to show. Whatever it was
+    // is still more useful than a second failure.
+    return String(error instanceof Error ? (error.stack ?? error.message) : error)
+  }
+}
+
+function render(error: unknown, options: RenderOptions, seen: Set<unknown>): string {
+  const colors = options.colors === undefined ? forStream() : palette(options.colors)
+  const cwd = options.cwd ?? process.cwd()
+
+  if (!(error instanceof Error)) {
+    return `\n  ${colors.red('Error')}  ${String(error)}\n`
+  }
+  // A cause that points back at something already rendered would recurse
+  // forever; errors do get wired in circles.
+  if (seen.has(error)) return ''
+  seen.add(error)
+
+  const out: string[] = ['']
+  const name = error.name === '' ? 'Error' : error.name
+  out.push(`  ${colors.bgRed(colors.white(` ${name} `))} ${colors.red(error.message)}`)
+
+  const frames = parseStack(error.stack, cwd)
+  const first = frames.find((frame) => frame.origin === 'application') ?? frames[0]
+
+  if (first !== undefined) {
+    const excerpt = sourceExcerpt(first, options.context ?? 3, colors)
+    if (excerpt.length > 0) {
+      out.push('')
+      out.push(`  ${colors.dim(`${relativeTo(first.file, cwd)}:${first.line}:${first.column}`)}`)
+      out.push('')
+      out.push(...excerpt)
+    }
+  }
+
+  const trace = frames.filter((frame) => frame.origin !== 'runtime')
+  if (trace.length > 0) {
+    out.push('')
+    for (const frame of trace.slice(0, 12)) {
+      const where = `${relativeTo(frame.file, cwd)}:${frame.line}`
+      const callee = frame.callee === undefined ? '' : `${frame.callee} `
+      const line = `    at ${callee}${where}`
+      // A frame from a dependency is dimmed rather than dropped: it is where
+      // the failure passed through, and hiding it makes a trace lie.
+      out.push(frame.origin === 'application' ? line : colors.dim(line))
+    }
+  }
+
+  const cause = 'cause' in error ? error.cause : undefined
+  if (cause !== undefined && cause !== null) {
+    const rendered = render(cause, options, seen)
+    if (rendered !== '') {
+      out.push('')
+      out.push(`  ${colors.dim('caused by')}`)
+      out.push(rendered)
+    }
+  }
+
+  out.push('')
+  return out.join('\n')
+}
+
+/**
+ * The failing line, with the ones around it.
+ *
+ * Empty when the file cannot be read — a frame inside a bundle, a file deleted
+ * since the process started, a permission. The trace still prints.
+ */
+function sourceExcerpt(
+  frame: StackFrame,
+  context: number,
+  colors: ReturnType<typeof ansiColors>,
+): string[] {
+  let source: string
+  try {
+    source = readFileSync(frame.file, 'utf8')
+  } catch {
+    return []
+  }
+
+  const lines = source.split('\n')
+  const start = Math.max(1, frame.line - context)
+  const end = Math.min(lines.length, frame.line + context)
+  const gutter = String(end).length
+
+  const out: string[] = []
+  for (let number = start; number <= end; number++) {
+    const text = lines[number - 1] ?? ''
+    const label = String(number).padStart(gutter, ' ')
+    if (number === frame.line) {
+      out.push(`  ${colors.red('❯')} ${colors.red(label)} │ ${text}`)
+      if (frame.column > 0) {
+        // The caret under the column the runtime reported. Tabs are copied
+        // across so the caret lands under the character, not beside it.
+        const prefix = text.slice(0, frame.column - 1).replace(/[^\t]/g, ' ')
+        out.push(`    ${' '.repeat(gutter)} │ ${prefix}${colors.red('^')}`)
+      }
+    } else {
+      out.push(`    ${colors.dim(label)} ${colors.dim('│')} ${colors.dim(text)}`)
+    }
+  }
+  return out
+}
+
+/** `file:///a/b.ts` and `/a/b.ts` both name the same file. */
+function toPath(location: string): string {
+  if (!location.startsWith('file:')) return location
+  try {
+    return fileURLToPath(location)
+  } catch {
+    return location
+  }
+}
+
+function originOf(file: string, cwd: string): StackFrame['origin'] {
+  if (file.startsWith('node:') || !file.includes(sep)) return 'runtime'
+  if (file.includes(`${sep}node_modules${sep}`)) return 'dependency'
+  return file.startsWith(cwd) ? 'application' : 'dependency'
+}
+
+/**
+ * The shortest path that still says where a frame is.
+ *
+ * A dependency frame is cut back to what comes after the last
+ * `node_modules/`, because the part before it is a store layout nobody reads:
+ * `@vitest/runner/dist/chunk-artifact.js`, not
+ * `…/.pnpm/@vitest+runner@4.1.11/node_modules/@vitest/runner/dist/…`.
+ */
+function relativeTo(file: string, cwd: string): string {
+  if (file.startsWith('node:')) return file
+  const marker = `${sep}node_modules${sep}`
+  const last = file.lastIndexOf(marker)
+  if (last !== -1) return file.slice(last + marker.length)
+  const path = relative(cwd, file)
+  return path === '' || path.startsWith('..') ? file : path
+}
+
+function forStream(): ReturnType<typeof ansiColors> {
+  return supportsColor(process.stderr) ? ansiColors() : silentColors()
+}
+
+function palette(on: boolean): ReturnType<typeof ansiColors> {
+  return on ? ansiColors() : silentColors()
+}

package/src/hot.ts

@@ -28,7 +28,7 @@ import { readFile } from 'node:fs/promises'
 import { registerHooks } from 'node:module'
 import { dirname, relative, resolve as resolvePath } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { fullReloadNotice } from './dev/fullReload.js'
+import { clearScreen, fullReloadNotice, invalidatedNotice } from './dev/fullReload.js'
 import { hotReloadHappened } from './dev/hmr.js'
 import { readHotHookConfig } from './dev/hotConfig.js'
 import { globMatcher } from './dev/hotGlob.js'
@@ -184,10 +184,20 @@ watchProject({
     ...reloadPatterns.map(watchRootOf).filter((dir) => dir !== ''),
   ],
   files: [...restartFiles].map((file) => relative(root, file)),
+  // A watcher that quietly stops watching is how this went unnoticed for a
+  // release: the first save swapped, the rest did nothing at all.
+  onWarning: (message) => sayNow(`[ream] hot reload — ${message}`),
   onChange: (file) => {
     const decision = graph.decide(file)
+    // Silent, as upstream is: a file the running process never imported has
+    // nothing to swap and nothing to restart for, and upstream's dev server
+    // returns without a word when its own inspection comes back empty.
     if (decision.kind === 'ignore') return
     if (decision.kind === 'reload') {
+      // Upstream clears the terminal before this line, so the logs that follow
+      // the restart are the only ones on screen. `--no-clear` turns it off,
+      // which is the flag `ace serve` gives for the same thing.
+      clearScreen()
       sayNow(fullReloadNotice(decision.file, decision.reason, relativeToRoot))
       // Exiting on a known code is how the Rust parent learns it must restart —
       // see `EXIT_RESTART` in the CLI's dev module.
@@ -198,6 +208,6 @@ watchProject({
     // process keeps serving the class it promoted: a stable PID and stale
     // output, which is exactly how it was first reported.
     hotReloadHappened()
-    sayNow(`[ream] hot swap — ${relativeToRoot(file)}`)
+    sayNow(invalidatedNotice(file, relativeToRoot))
   },
 })

package/src/index.ts

@@ -249,6 +249,12 @@ export type {
   CommandOptions,
   FlagMetaData,
 } from './console/types.js'
+export {
+  parseStack,
+  type RenderOptions,
+  renderError,
+  type StackFrame,
+} from './errors/renderError.js'
 export type {
   HyperServerLike,
   IgnitorConfig,
@@ -272,8 +278,22 @@ export type {
 
 // ─── Codemods ───────────────────────────────────────────────
 
-export type { Codemods } from './Codemods.js'
-export { createCodemods } from './Codemods.js'
+export {
+  type Codemods,
+  createCodemods,
+  type GeneratedStub,
+  type StubState,
+} from './Codemods.js'
+export {
+  compile as compileStub,
+  escapeHtml,
+  generate as generateStub,
+  render as renderStub,
+  type StubBlock,
+  StubSyntaxError,
+  type StubValue,
+  type TemplateOptions,
+} from './stubs/template.js'
 
 // ─── Errors ─────────────────────────────────────────────────
 
@@ -385,4 +405,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.25'
+export const VERSION = '0.2.27'

package/src/profiler/MemoryProfileStore.ts

@@ -0,0 +1,75 @@
+/**
+ * Where profiles live during a dev session.
+ *
+ * In memory and bounded. Symfony writes its profiles to disk so they survive a
+ * restart; here a restart is the common case — every saved file changes it —
+ * and a dev server that grows a directory nobody empties is a worse trade than
+ * losing the history of the session you just ended.
+ *
+ * The bound is a count, not a size: a profile holding 400 queries is the one
+ * you most want to keep, and dropping it for being big would lose exactly the
+ * request worth looking at.
+ */
+
+import type { Profile, ProfilerCollector, ProfileStore, ProfileSummary } from './types.js'
+
+/** How many requests are remembered. Enough to walk back through a flow. */
+const DEFAULT_LIMIT = 50
+
+export class MemoryProfileStore implements ProfileStore {
+  readonly #profiles = new Map<string, Profile>()
+  readonly #limit: number
+  readonly #collectors: readonly ProfilerCollector[]
+
+  constructor(collectors: readonly ProfilerCollector[] = [], limit = DEFAULT_LIMIT) {
+    this.#collectors = collectors
+    this.#limit = Math.max(1, limit)
+  }
+
+  save(profile: Profile): void {
+    this.#profiles.set(profile.token, profile)
+    // A Map iterates in insertion order, so the oldest key is the first one.
+    while (this.#profiles.size > this.#limit) {
+      const oldest = this.#profiles.keys().next()
+      if (oldest.done === true) break
+      this.#profiles.delete(oldest.value)
+    }
+  }
+
+  find(token: string): Profile | undefined {
+    return this.#profiles.get(token)
+  }
+
+  /** Newest first, which is the order anyone reading a history wants. */
+  recent(limit = 20): ProfileSummary[] {
+    const summaries: ProfileSummary[] = []
+    for (const profile of [...this.#profiles.values()].reverse()) {
+      if (summaries.length >= limit) break
+      summaries.push(this.#summarise(profile))
+    }
+    return summaries
+  }
+
+  clear(): void {
+    this.#profiles.clear()
+  }
+
+  /**
+   * The headline each collector wants shown.
+   *
+   * Asked of the collector rather than computed here: what counts as the
+   * headline of a panel is the panel's business, and a store that knew would
+   * have to be changed every time one is added.
+   */
+  #summarise(profile: Profile): ProfileSummary {
+    const badges: Record<string, string> = {}
+    for (const collector of this.#collectors) {
+      const data = profile.data[collector.name]
+      if (data === undefined || collector.badge === undefined) continue
+      const badge = collector.badge(data)
+      if (badge !== undefined) badges[collector.name] = badge
+    }
+    const { data: _data, ...rest } = profile
+    return { ...rest, badges }
+  }
+}