@c9up/ream 0.2.25 → 0.2.27

package/src/console/selection.ts

@@ -0,0 +1,274 @@
+/**
+ * Picking from a list with the arrow keys.
+ *
+ * Upstream's prompts are enquirer, so its selection prompts navigate: up and
+ * down move a pointer, space ticks a box, enter answers. Typing a number
+ * instead — which is what this package did — is the same prompt only in the
+ * sense that it eventually returns a value.
+ *
+ * Written here rather than taken from a package, for the reason lumen was
+ * written rather than `@poppinss/cliui` taken: a dev-time dependency is a
+ * dependency every application installs. What a selection prompt needs is
+ * bounded — raw mode, five keys, and redrawing in place — and it is all below.
+ *
+ * Only ever entered on a TTY. A prompt with nothing to read from is refused
+ * before this by the caller, which is what makes the loop here able to assume
+ * a terminal.
+ */
+
+import { stdin, stdout } from 'node:process'
+import { clearLine, cursorTo, moveCursor } from 'node:readline'
+import { ReamError } from '../errors/ReamError.js'
+import { colourise } from './ui.js'
+
+/** One line of the list, as the renderer needs it. */
+export interface SelectionItem {
+  label: string
+  hint?: string
+}
+
+export interface SelectionOptions {
+  /** Printed above the list. */
+  title: string
+  items: readonly SelectionItem[]
+  /** Tick boxes and let several be picked. */
+  many?: boolean
+  /** Where the pointer starts, and what is ticked to begin with. */
+  selected?: readonly number[]
+  /** Type to narrow the list — the autocomplete case. */
+  filter?: boolean
+  /** How many lines of the list to show at once. */
+  limit?: number
+  /** Where the keys come from. Defaults to this process's stdin. */
+  input?: NodeJS.ReadStream
+  /** Where the list is drawn. Defaults to this process's stdout. */
+  output?: NodeJS.WriteStream
+}
+
+/** What the user did. Cancelling is not an empty answer, it is no answer. */
+export type SelectionResult = { kind: 'picked'; indexes: number[] } | { kind: 'cancelled' }
+
+const ARROW_UP = '\u001B[A'
+const ARROW_DOWN = '\u001B[B'
+const ARROW_LEFT = '\u001B[D'
+const ARROW_RIGHT = '\u001B[C'
+const ENTER = ['\r', '\n']
+const CTRL_C = '\u0003'
+const CTRL_D = '\u0004'
+const ESCAPE = '\u001B'
+const BACKSPACE = ['\u0008', '\u007F']
+
+/**
+ * Run the list until the user answers.
+ *
+ * Resolves with the chosen indexes, in the order they were ticked for a
+ * multiple — the order the user built them in is the order they expect back.
+ */
+export function runSelection(options: SelectionOptions): Promise<SelectionResult> {
+  if (options.items.length === 0) {
+    return Promise.reject(
+      new ReamError('E_CONSOLE_EMPTY_CHOICES', `"${options.title}" was asked with no options.`),
+    )
+  }
+
+  const input = options.input ?? stdin
+  const output = options.output ?? stdout
+
+  const state = {
+    // The pointer starts on the default rather than at the top: for a single
+    // choice that IS the default, since enter takes whatever it is on.
+    cursor: Math.max(0, options.selected?.[0] ?? 0),
+    ticked: new Set<number>(options.selected ?? []),
+    query: '',
+    /** Lines drawn last time, so the next draw can wipe exactly those. */
+    drawn: 0,
+  }
+  const limit = Math.max(1, options.limit ?? 10)
+
+  const visible = (): number[] => {
+    if (options.filter !== true || state.query === '') return options.items.map((_, i) => i)
+    const needle = state.query.toLowerCase()
+    return options.items
+      .map((_, index) => index)
+      .filter((index) => (options.items[index]?.label ?? '').toLowerCase().includes(needle))
+  }
+
+  return new Promise<SelectionResult>((resolve, reject) => {
+    const finish = (result: SelectionResult): void => {
+      erase(output, state.drawn)
+      teardown()
+      resolve(result)
+    }
+
+    const onData = (chunk: Buffer | string): void => {
+      const key = chunk.toString()
+      const shown = visible()
+
+      if (key === CTRL_C || key === CTRL_D || key === ESCAPE) {
+        finish({ kind: 'cancelled' })
+        return
+      }
+
+      if (ENTER.includes(key)) {
+        if (options.many === true) {
+          finish({ kind: 'picked', indexes: [...state.ticked] })
+          return
+        }
+        const index = shown[state.cursor]
+        // Enter on a filter that matches nothing answers nothing: there is no
+        // line under the pointer to take.
+        if (index === undefined) return
+        finish({ kind: 'picked', indexes: [index] })
+        return
+      }
+
+      if (key === ARROW_UP) {
+        state.cursor = state.cursor === 0 ? shown.length - 1 : state.cursor - 1
+      } else if (key === ARROW_DOWN) {
+        state.cursor = state.cursor === shown.length - 1 ? 0 : state.cursor + 1
+      } else if (options.many === true && key === ' ') {
+        const index = shown[state.cursor]
+        if (index !== undefined) {
+          if (state.ticked.has(index)) state.ticked.delete(index)
+          else state.ticked.add(index)
+        }
+      } else if (options.many === true && (key === ARROW_LEFT || key === ARROW_RIGHT)) {
+        // Upstream's multiple ticks and unticks with left and right too.
+        const index = shown[state.cursor]
+        if (index !== undefined) {
+          if (key === ARROW_RIGHT) state.ticked.add(index)
+          else state.ticked.delete(index)
+        }
+      } else if (options.filter === true && BACKSPACE.includes(key)) {
+        state.query = state.query.slice(0, -1)
+        state.cursor = 0
+      } else if (options.filter === true && isTypable(key)) {
+        state.query += key
+        state.cursor = 0
+      } else {
+        // A key nothing is bound to must not redraw: a mouse event arrives as
+        // a burst of escape sequences, and redrawing on each one flickers.
+        return
+      }
+
+      draw()
+    }
+
+    const draw = (): void => {
+      erase(output, state.drawn)
+      const shown = visible()
+      if (state.cursor >= shown.length) state.cursor = Math.max(0, shown.length - 1)
+
+      const lines: string[] = [heading(options, state.query)]
+      const window = windowOf(shown.length, state.cursor, limit)
+      for (let row = window.start; row < window.end; row++) {
+        const index = shown[row]
+        if (index === undefined) continue
+        const item = options.items[index]
+        if (item === undefined) continue
+        lines.push(
+          renderItem(item, row === state.cursor, options.many === true, state.ticked.has(index)),
+        )
+      }
+      if (shown.length === 0) lines.push(colourise('  no match', 'dim'))
+      if (shown.length > window.end - window.start) {
+        lines.push(colourise(`  … ${shown.length - (window.end - window.start)} more`, 'dim'))
+      }
+
+      for (const line of lines) output.write(`${line}\n`)
+      state.drawn = lines.length
+    }
+
+    const teardown = (): void => {
+      input.removeListener('data', onData)
+      if (input.isTTY) input.setRawMode(false)
+      input.pause()
+    }
+
+    try {
+      if (!input.isTTY) {
+        throw new ReamError(
+          'E_CONSOLE_NOT_INTERACTIVE',
+          `Cannot prompt for "${options.title}" — stdin is not interactive.`,
+          { hint: 'Pass the value as a flag, or script the answer with prompt.trap(name).' },
+        )
+      }
+      input.setRawMode(true)
+      input.resume()
+      input.on('data', onData)
+      draw()
+    } catch (error) {
+      teardown()
+      reject(error)
+    }
+  })
+}
+
+/** The title line, with what has been typed so far when there is a filter. */
+function heading(options: SelectionOptions, query: string): string {
+  const help =
+    options.many === true
+      ? colourise(' (space to pick, enter to confirm)', 'dim')
+      : colourise(' (use arrow keys)', 'dim')
+  const typed = options.filter === true && query !== '' ? ` ${colourise(query, 'cyan')}` : ''
+  return `${colourise('?', 'green')} ${options.title}${typed}${help}`
+}
+
+/**
+ * One line of the list.
+ *
+ * A pointer says where you are; a box, only on a multiple, says what is
+ * taken. Without the box a multiple has no way to show four ticks at once,
+ * which is the whole of what it is for.
+ */
+function renderItem(
+  item: SelectionItem,
+  underCursor: boolean,
+  many: boolean,
+  ticked: boolean,
+): string {
+  const pointer = underCursor ? colourise('❯', 'cyan') : ' '
+  const box = many ? `${ticked ? colourise('◉', 'cyan') : '◯'} ` : ''
+  const label = underCursor ? colourise(item.label, 'cyan') : item.label
+  const hint = item.hint === undefined ? '' : colourise(` — ${item.hint}`, 'dim')
+  return `${pointer} ${box}${label}${hint}`
+}
+
+/**
+ * Which slice of a long list to show.
+ *
+ * Kept around the cursor rather than paged: a pointer that walks off the
+ * bottom and reappears at the top of a new page loses the reader.
+ */
+function windowOf(total: number, cursor: number, limit: number): { start: number; end: number } {
+  if (total <= limit) return { start: 0, end: total }
+  const half = Math.floor(limit / 2)
+  const start = Math.min(Math.max(0, cursor - half), total - limit)
+  return { start, end: start + limit }
+}
+
+/** Wipe the lines drawn last time, so the next draw replaces them. */
+function erase(output: NodeJS.WriteStream, lines: number): void {
+  if (lines === 0) return
+  for (let row = 0; row < lines; row++) {
+    moveCursor(output, 0, -1)
+    cursorTo(output, 0)
+    clearLine(output, 0)
+  }
+}
+
+/**
+ * Printable text, and not an escape sequence.
+ *
+ * A chunk, not a character: typing quickly — or pasting — delivers several at
+ * once, and a filter that took only single-character chunks silently dropped
+ * everything typed faster than the event loop.
+ */
+function isTypable(chunk: string): boolean {
+  if (chunk.length === 0) return false
+  for (const character of chunk) {
+    const code = character.codePointAt(0) ?? 0
+    if (code < 0x20 || code === 0x7f) return false
+  }
+  return true
+}

package/src/console/ui.ts

@@ -1,37 +1,25 @@
 /**
- * Console UI — `this.logger` and `this.prompt` on every command (Console parity).
+ * The one colour helper the Kernel's help and the prompts use.
  *
- * Kept dependency-free: the framework ships no colour or prompt library, and
- * pulling one in for the CLI surface alone is not worth the install weight.
+ * It is a thin call into `@c9up/lumen` rather than a second palette: two
+ * tables of escape codes in one package is how `[ warn ]` ends up yellow in
+ * one command and plain in another.
+ *
+ * The environment is read on EVERY call, not cached, because a command can be
+ * run in-process with the environment changed around it — which is exactly
+ * what the tests covering `FORCE_COLOR` do.
  */
 
 import { stdout } from 'node:process'
+import { ansiColors, type Colors, silentColors, supportsColor } from '@c9up/lumen'
 
-/** Colour is opt-out via NO_COLOR and skipped when piped to a file. */
-function supportsColour(stream: NodeJS.WriteStream): boolean {
-  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
-  if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '') return true
-  return Boolean(stream.isTTY)
-}
-
-const CODES = {
-  reset: '\u001B[0m',
-  dim: '\u001B[2m',
-  red: '\u001B[31m',
-  green: '\u001B[32m',
-  yellow: '\u001B[33m',
-  blue: '\u001B[34m',
-  magenta: '\u001B[35m',
-  cyan: '\u001B[36m',
-} as const
-
-export type Colour = keyof Omit<typeof CODES, 'reset'>
+export type Colour = 'dim' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan'
 
 export function colourise(
   text: string,
   colour: Colour,
   stream: NodeJS.WriteStream = stdout,
 ): string {
-  if (!supportsColour(stream)) return text
-  return `${CODES[colour]}${text}${CODES.reset}`
+  const colors: Colors = supportsColor(stream) ? ansiColors() : silentColors()
+  return colors[colour](text)
 }

package/src/dev/fullReload.ts

@@ -1,34 +1,76 @@
 /**
- * Saying why the process is about to restart.
+ * What the dev server says when a file changed.
  *
- * A change the loader cannot swap in place becomes an exit code the dev server
- * restarts on. From the terminal the only trace of it was the boot banner
- * printing itself a second time — which reads as a server rebooting on its own
- * rather than as a file that fell outside `hotHook.boundaries`. Upstream's dev
- * server logs the file it reloaded for; this is that line.
+ * Upstream's vocabulary, read off `@adonisjs/assembler`'s build rather than
+ * invented: a module the loader swapped in place is `invalidated <path>`, and
+ * one that could not be — so the process restarts — is `update <path>`. The
+ * word is green, the path is not, and that is the whole line.
+ *
+ * It used to carry the reason as well: which `hotHook` entry the file fell
+ * outside of. That read well the first time and was noise every time after,
+ * and it is not what upstream prints. What the reason existed for — a boot
+ * banner appearing twice with nothing to explain it — is answered by the line
+ * being there at all.
+ *
+ * The terminal is cleared first, as upstream clears it, so the logs after a
+ * restart are the only ones on screen. `ream dev --no-clear` turns it off —
+ * `ace serve --no-clear` is the same flag for the same reason.
  *
  * Kept apart from the loader entry so it can be tested: importing that entry
  * registers module hooks, which a test cannot undo.
  */
 
+import { ansiColors, silentColors, supportsColor } from '@c9up/lumen'
+
 /** Why a change could not be swapped in place. */
 export type ReloadReason = 'outside-boundaries' | 'restart-list'
 
 /**
- * The line to print before restarting.
+ * Coloured only when the stream takes colour.
+ *
+ * Decided per call rather than once at import: this module is loaded by the
+ * hot entry long before anything knows where its output goes, and a cached
+ * answer would be the wrong one for a piped run.
+ */
+function colors(): ReturnType<typeof ansiColors> {
+  return supportsColor(process.stdout) ? ansiColors() : silentColors()
+}
+
+/**
+ * Wipe the terminal, the way upstream does before a restart.
+ *
+ * `\u001Bc` is the full reset upstream writes, not a scroll — the point is
+ * that what follows is the only thing on screen. Off when the dev server was
+ * started with `--no-clear`, and off when nothing is watching a terminal at
+ * all: writing escape codes into a pipe leaves them in the file.
+ */
+export function clearScreen(): void {
+  if (process.env.REAM_DEV_CLEAR_SCREEN === 'false') return
+  if (!process.stdout.isTTY) return
+  process.stdout.write('\u001Bc')
+}
+
+/**
+ * The line printed when a module was swapped in the running process.
  *
  * @param file - absolute path of the file that changed.
- * @param relativise - turns it into the path the editor shows, so the line can
- *   be read at a glance.
+ * @param relativise - turns it into the path the editor shows.
+ */
+export function invalidatedNotice(file: string, relativise: (file: string) => string): string {
+  return `${colors().green('invalidated')} ${relativise(file)}`
+}
+
+/**
+ * The line printed before the process restarts.
+ *
+ * `reason` is not in the text — it is what the caller already decided, and
+ * upstream prints one word — but it stays in the signature because the caller
+ * has it and a future line may want it.
  */
 export function fullReloadNotice(
   file: string,
-  reason: ReloadReason,
+  _reason: ReloadReason,
   relativise: (file: string) => string,
 ): string {
-  const why =
-    reason === 'restart-list'
-      ? ' (it is on `hotHook.restart`, which always restarts)'
-      : ' (nothing importing it is inside a `hotHook.boundaries` entry, so it could not be swapped)'
-  return `[ream] full reload — ${relativise(file)}${why}`
+  return `${colors().green('update')} ${relativise(file)}`
 }

package/src/dev/hotWatcher.ts

@@ -1,9 +1,23 @@
 /**
  * Watching the project for the changes a hot reload reacts to.
  *
- * `fs.watch` with `recursive: true`, which Node implements on Linux, macOS and
- * Windows alike — the reason a watcher used to be a dependency here, and is not
- * any more.
+ * ONE `fs.watch` PER DIRECTORY, walked ourselves — not `recursive: true`, and
+ * never a watch on a file. That is not a preference, it is the bug this module
+ * was reported for: most editors save by writing a temporary file and renaming
+ * it over the original (JetBrains IDEs, several formatters, anything using
+ * write-and-replace for crash safety). The rename gives the path a NEW inode,
+ * and a watcher holding the old one is watching something that no longer has a
+ * name. Measured on Node 25, Linux:
+ *
+ *     fs.watch(dir, { recursive: true })   first rename fires, then silence
+ *     fs.watch(file)                       first rename fires, then silence
+ *     fs.watch(dir)                        every rename fires
+ *
+ * So the first save hot-swapped and every one after it was ignored without a
+ * word — no reload, no restart, nothing in the log. A directory keeps its inode
+ * when a file inside it is replaced, which is why watching directories is the
+ * form that survives. A file to watch is watched through its parent instead,
+ * filtered by name.
  *
  * Two behaviours are worth stating because they are not obvious from the API:
  *
@@ -18,12 +32,33 @@
  * that window, and hands back over by restarting the process.
  */
 
-import { type FSWatcher, watch } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { type FSWatcher, readdirSync, realpathSync, statSync, watch } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
 
 /** How long to wait for a save to finish arriving before acting on it. */
 const SETTLE_MS = 40
 
+/** Never walked: none of it is application source, and some of it is enormous. */
+const SKIP_DIRECTORIES = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.wolf'])
+
+/**
+ * The half-written files an atomic save leaves behind for a few milliseconds.
+ *
+ * Reported, they would be a change to `Controller.ts.tmp8f3` — a file the graph
+ * has never heard of, on its way to being renamed into the one that matters.
+ */
+function isEditorArtefact(name: string): boolean {
+  return (
+    name.endsWith('~') ||
+    name.endsWith('.swp') ||
+    name.endsWith('.swx') ||
+    name.startsWith('.#') ||
+    name.startsWith('.goutputstream') ||
+    /\.tmp[\w-]*$/.test(name) ||
+    /^\.?[\w.-]+\.(?:tmp|temp|crswap|part|partial)$/i.test(name)
+  )
+}
+
 export interface WatcherOptions {
   /** Project root; every reported path is absolute, resolved against it. */
   root: string
@@ -33,6 +68,8 @@ export interface WatcherOptions {
   files: readonly string[]
   /** Called once per settled change, with an absolute path. */
   onChange: (file: string) => void
+  /** Told when a directory could not be watched for a reason worth knowing. */
+  onWarning?: (message: string) => void
 }
 
 export interface Watcher {
@@ -40,8 +77,11 @@ export interface Watcher {
 }
 
 export function watchProject(options: WatcherOptions): Watcher {
-  const watchers: FSWatcher[] = []
+  const watchers = new Map<string, FSWatcher>()
   const pending = new Map<string, NodeJS.Timeout>()
+  /** Real paths already walked, so a symlink loop cannot spin forever. */
+  const visited = new Set<string>()
+  let closed = false
 
   const report = (file: string): void => {
     const existing = pending.get(file)
@@ -55,35 +95,139 @@ export function watchProject(options: WatcherOptions): Watcher {
     pending.set(file, timer)
   }
 
-  for (const directory of options.directories) {
-    const absolute = resolve(options.root, directory)
+  const warn = (message: string): void => options.onWarning?.(message)
+
+  /**
+   * Watch one directory, then everything under it.
+   *
+   * Called again for a directory that appears later: a `mkdir app/billing`
+   * during a session must be watched, and the parent's event is what says so.
+   *
+   * `announce` closes the gap between that mkdir and the watch being in place.
+   * `mkdir -p app/billing && cp Controller.ts app/billing/` writes the file
+   * before the watcher on the new directory exists, so what is already inside a
+   * directory discovered mid-session is reported as a change. At startup it is
+   * false, or booting would report every file in the project.
+   */
+  const watchDirectory = (absolute: string, announce = false): void => {
+    if (closed || watchers.has(absolute)) return
+
+    let real: string
+    try {
+      real = realpathSync(absolute)
+      if (!statSync(real).isDirectory()) return
+    } catch (error) {
+      // Absent is ordinary — the list is the framework's conventional layout,
+      // not a requirement, and a directory can be removed mid-session. Any
+      // other reason (no permission, too many open files) is worth saying, or
+      // the project silently stops hot-reloading.
+      if (!isMissing(error)) warn(`cannot watch ${absolute}: ${describe(error)}`)
+      return
+    }
+    if (visited.has(real)) return
+    visited.add(real)
+
+    try {
+      const watcher = watch(absolute, (_event, name) => {
+        if (typeof name !== 'string' || name === '') return
+        const child = join(absolute, name)
+        // A new directory has to be picked up, or nothing in it is ever seen.
+        // Cheap: only for names that are directories right now.
+        if (!SKIP_DIRECTORIES.has(name) && isDirectory(child)) watchDirectory(child, true)
+        if (isEditorArtefact(name)) return
+        report(child)
+      })
+      watcher.on('error', (error) => {
+        // A watcher whose directory was removed is done; anything else is a
+        // surprise the developer should hear about rather than lose.
+        watchers.delete(absolute)
+        if (!isMissing(error)) warn(`watch on ${absolute} failed: ${describe(error)}`)
+      })
+      watchers.set(absolute, watcher)
+    } catch (error) {
+      if (!isMissing(error)) warn(`cannot watch ${absolute}: ${describe(error)}`)
+      return
+    }
+
+    let entries: string[] = []
     try {
-      watchers.push(
-        watch(absolute, { recursive: true }, (_event, name) => {
-          if (typeof name !== 'string' || name === '') return
-          report(join(absolute, name))
-        }),
-      )
-    } catch {
-      // A directory this project does not have is not an error: the list is
-      // the framework's conventional layout, not a requirement.
+      entries = readdirSync(absolute)
+    } catch (error) {
+      if (!isMissing(error)) warn(`cannot read ${absolute}: ${describe(error)}`)
+      return
     }
+    for (const entry of entries) {
+      if (SKIP_DIRECTORIES.has(entry)) continue
+      const child = join(absolute, entry)
+      if (isDirectory(child)) {
+        watchDirectory(child, announce)
+        continue
+      }
+      if (announce && !isEditorArtefact(entry)) report(child)
+    }
+  }
+
+  for (const directory of options.directories) {
+    watchDirectory(resolve(options.root, directory))
   }
 
+  // A file is watched through its parent directory, for the reason at the top
+  // of this module: `fs.watch` on the file itself holds an inode, and an atomic
+  // save replaces it. `.env` is saved by the same editors as everything else.
+  const watchedFiles = new Map<string, Set<string>>()
   for (const file of options.files) {
     const absolute = resolve(options.root, file)
+    const parent = dirname(absolute)
+    const names = watchedFiles.get(parent) ?? new Set<string>()
+    names.add(basename(absolute))
+    watchedFiles.set(parent, names)
+  }
+
+  for (const [parent, names] of watchedFiles) {
+    // The parent may already be covered as a watched directory — `.env` sits at
+    // the root, which is not in the list, but a caller is free to pass both.
+    if (watchers.has(parent)) continue
     try {
-      watchers.push(watch(absolute, () => report(absolute)))
-    } catch {
-      // Same: a `.env` that does not exist is simply not watched.
+      const watcher = watch(parent, (_event, name) => {
+        if (typeof name !== 'string' || !names.has(name)) return
+        report(join(parent, name))
+      })
+      watcher.on('error', (error) => {
+        watchers.delete(parent)
+        if (!isMissing(error)) warn(`watch on ${parent} failed: ${describe(error)}`)
+      })
+      watchers.set(parent, watcher)
+    } catch (error) {
+      if (!isMissing(error)) warn(`cannot watch ${parent}: ${describe(error)}`)
     }
   }
 
   return {
     close: () => {
+      closed = true
       for (const timer of pending.values()) clearTimeout(timer)
       pending.clear()
-      for (const watcher of watchers) watcher.close()
+      for (const watcher of watchers.values()) watcher.close()
+      watchers.clear()
     },
   }
 }
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** ENOENT and friends: the path is simply not there, which is not a failure. */
+function isMissing(error: unknown): boolean {
+  const code = (error as { code?: unknown }).code
+  return code === 'ENOENT' || code === 'ENOTDIR'
+}
+
+function describe(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return String(error)
+}